Настройки режима «Протектор4J» на продвинутом уровне

Режим на продвинутом уровне позволяет вручную определять область защиты, параметры совместимости и специфические настройки для конкретных типов приложений. При первой обработке нового приложения рекомендуется сначала использовать простой режим или провести сканирование совместимости на странице настроек на продвинутом уровне, а затем скорректировать настройки на основе результатов сканирования.

Данная статья является подробным описанием режима на продвинутом уровне в Руководство по использованию GUI. Для определения того, какие классы следует оставить без шифрования, рекомендуется ознакомиться с Совместимость и область защиты; при написании автоматизированных команд следует руководствоваться Справка по параметрам CLI.

1. Переход в режим на продвинутом уровне

1. Выбор типа приложения и ввод имени файла в формате JAR/WAR.
2. Выбор Входящая версия Java и по меньшей мере одной целевой платформы.
3. Выбор Advanced — customise the options yourself в Mode.
4. Нажмите на Next, чтобы перейти на страницу настроек на продвинутом уровне.

Если вы уже находитесь на странице подтверждения вывода, вы можете нажать Customize…, чтобы вернуться на страницу продвинутых параметров. После внесения изменений снова перейдите на страницу вывода, чтобы убедиться, что резюме отражает новые настройки.

Версию Java и целевую платформу нельзя изменять на странице продвинутых параметров; при необходимости возвращайтесь на страницу ввода. Для задач с несколькими платформами генерируется отдельный результат для каждой из них, причем vlxjre нельзя использовать вместо друг друга.

2. Общие опции

Четыре типа приложений используют общую область продвинутых параметров, но некоторые настройки применяются в зависимости от типа. Для функции Library Encryption не генерируется скрипт запуска, поэтому не используются параметры запуска JVM; настройки суффикса архива применяются для формирования и синхронизации имён выходных файлов.

Специфические настройки, реально используемые для различных типов приложений, приведены ниже:

“Не исключается подобный класс” означает, что по умолчанию осуществляется защита всех приложений данного типа, однако это не включает защиту сторонних зависимостей. BOOT-INF/lib для Spring Boot и WEB-INF/lib для Tomcat по умолчанию находятся в обычном режиме.

Расширение архива

При выборе jar изменяется только имя файла, а его содержимое остается в формате P4JX. Его нельзя изменять с помощью обычных инструментов ZIP/JAR, а также нельзя загружать с использованием обычного JRE. В режиме Library Encryption это настройка приводит к замене суффикса выбранного выходного файла на .p4jx/.jar; если пользователь указал другой пользовательский суффикс, то полное имя файла сохраняется без изменений.

Соответствующий CLI:

--archive-suffix p4jx
--archive-suffix jar

Запрет на метод защиты JIT

После включения Disable JIT for protected methods методы защиты не будут использовать JIT-компилятор, что позволяет сократить объем разглашаемого машинного кода после компиляции, однако вычислительно интенсивный код может значительно замедлиться. Эта настройка влияет только на методы защиты и не приводит к переключению всей JVM в режим чистой интерпретации.

Соответствующий CLI:

--no-jit

Сканер ZIP overlay

overlay выдает в обзор только публичные ресурсы, каталоги и метаданные классов защиты, не включая реальные тела методов. Он предназначен для совместимости с инструментами, которые читают центральный каталог ZIP напрямую, но не может заменить схему разметки Spring Boot fat, а также не решает проблемы парсинга архивов с использованием ZipInputStream/JarInputStream из потока памяти.

Соответствующая CLI:

--zip-overlay scanner

Параметры запуска JVM

В каждой строке указывается один полный параметр, например:

-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8

Каждая строка является границей параметра; не следует писать несколько параметров в одной строке. Параметры будут записаны в скрипты запуска для macOS/Linux и Windows; параметры Tomcat также попадут в его путь запуска. Library Encryption не генерирует скрипты запуска, поэтому поле ввода недоступно. Более полные примеры для различных платформ смотрите в Настройка параметров запуска JVM.

Для соответствующей CLI требуется повторное использование опций:

--jvm-option -Xms512m --jvm-option -Xmx2g

3. Сканирование совместимости и рекомендации по приложениям

Для всех четырех типов приложений можно нажать Compatibility scan…, чтобы просканировать текущий ввод. При принятии результата инструмент объединит рекомендации, подходящие для данного типа приложения, с текущими настройками; они в основном включают:

• Добавление классов, которые должны оставаться незашифрованными;
• Включение функции сканирования ZIP overlay для сканера;
• Настройка суффикса архива;
• Включение JavaFX/WebView для Java Application или Spring Boot;
• Выбор лейаута для Spring Boot;
• Выбор версии 9 или 10.1 для Tomcat.

Функция Library Encryption автоматически применяет только рекомендации по использованию ZIP overlay для сканера и суффиксов архивов. По своей конструкции она защищает все классы во входном JAR-файле, не поддерживая исключение классов; если в ходе сканирования обнаруживаются элементы, такие как JNI/нативные классы, которые должны оставаться незашифрованными, в отчёте чётко указывается необходимость вынести их в отдельный обычный JAR-файл или использовать режим упаковки приложения с поддержкой выборочной защиты.

После принятия рекомендаций возможно продолжить редактирование. Сканирование сохраняет существующие правила исключения и не отключает включённый пользователем JavaFX из-за отсутствия обнаружения JavaFX. Отмена диалогового окна приводит к отклонению рекомендаций.

Риски на уровне кода, указанные в отчёте сканирования, такие как использование Agent, JNI, пользовательских загрузчиков классов или изменение байт-кода во время выполнения, обычно невозможно устранить просто с помощью одного параметра. Необходимо скорректировать границы кода с использованием Совместимость и область защиты и провести практические тесты.

4. Настройки Java Application

Main class

При оставлении поля пустым используется значение Main-Class, взятое из манифеста входного JAR-файла. Полное имя класса указывается только тогда, когда в манифесте отсутствует основной класс или требуется замена стандартного класса запуска, например, com.example.Main.

Соответствующий CLI-параметр: --main com.example.Main.

Classes to exclude

Все классы приложения по умолчанию находятся в состоянии защиты. Классы или пакеты, указанные в этом списке, остаются незашифрованными; они подходят для DTO, сущностей, классов конфигурации, классов-мостов JNI, а также для классов, которым необходимо усиление со стороны фреймворка или чтение исходного байт-кода. Формат правил смотрите в “Область защиты и правила исключения”.

JavaFX runtime

Для обычных JavaFX-приложений отмечается пункт Bundle JavaFX into the packaged runtime. Для WebView доступны следующие варианты:

• Auto: включается при обнаружении javafx.scene.web;
• Include: обязательное включение fx-webkit;
• Exclude: обязательное отсутствие.

WebView увеличивает размер примерно на 40 МБ. GUI загружает ресурсы в соответствии с целевой версией Java и платформой; для указания локального офлайн-каталога JavaFX используется CLI.

Соответствующие CLI: --javafx, --javafx-webview и --no-javafx-webview. Auto не добавляет дополнительных опций для обязательного использования WebView — пакетизатор решает это в зависимости от ссылок в приложении.

5. Настройки Spring Boot

Main class

При оставлении пустым используется Start-Class, который читает информацию из Manifest. Для замены класса-запуска необходимо указать полное имя класса.

Соответствующий CLI: --main com.example.Application.

Layout

Если сканирование совместимости явно рекомендует fat, не следует просто включить ZIP overlay и при этом настаивать на использовании p4jx-fat. Подробности разметки смотрите в Защита приложений на Spring Boot.

Соответствующие CLI: --layout p4jx-fat, --layout fat или --layout separate.

Protect dependency JARs…

Зависимости в BOOT-INF/lib по умолчанию не защищаются. Выбирайте только собственные закрытые зависимости; не шифруйте пакеты сторонних фреймворков, таких как Spring, Tomcat, системы логирования и драйверы баз данных. Подписанные JAR-файлы будут отображаться как недоступные, поскольку любые изменения нарушат их подпись.

После выбора одной зависимости все её классы будут защищены, но правила Classes to exclude всё равно позволяют исключить определённые классы или пакеты для этой зависимости. Защита зависимостей поддерживается во всех трёх вариантах разметки Spring Boot.

Соответствующий CLI: --protect-lib 'company-core.jar,company-domain.jar'. CLI также поддерживает глоб-паттерны; в GUI сохраняется точное имя файла выбранного JAR-файла.

Классы для исключения и JavaFX

Способ использования такой же, как у Java Application. Правила исключения применяются как к классам приложения, так и к выбранным для защиты зависимостям в формате JAR. Для десктопных приложений на Spring Boot + JavaFX также можно упаковать компоненты JavaFX/WebView на вкладке JavaFX runtime.

6. Настройки Tomcat

Tomcat version

• Для WAR-файлов, используемых с javax.servlet.*, выбирается Tomcat 9 · javax;
• Для WAR-файлов, используемых с jakarta.servlet.*, выбирается Tomcat 10.1 · jakarta.

Для Tomcat 10.1 требуется как минимум Java 11. При неопределённости следует выполнить сканирование на совместимость; если приложение использует одновременно javax и jakarta, не стоит насильственно выбирать версию — сначала необходимо устранить конфликты зависимостей.

В режиме «Продвинутый» нет предустановленной версии, поэтому для перехода к следующему шагу необходимо либо принять рекомендации сканирования, либо вручную сделать выбор. Соответствующие варианты для CLI: --tomcat-version 9 или --tomcat-version 10; CLI также позволяет использовать auto.

Context path

Укажите путь развертывания, начинающийся с /, например, /app. При оставлении поля пустым используется /app. При добавлении приложения в существующую папку вывода Tomcat path контекста не должен совпадать с путями уже существующих приложений.

Соответствующий CLI: --context /app.

Classes to exclude

По умолчанию осуществляется защита классов приложения WEB-INF/classes; класс WEB-INF/lib по умолчанию не защищается. Как правило, следует исключать классы Servlet, Filter, Listener, DTO, конфигурационные элементы, сущности, классы-мосты JNI, а также классы, требующие дополнительной настройки в контейнере.

7. Область защиты и правила исключения

В режиме «Продвинутый» интерфейс GUI по умолчанию обеспечивает защиту всех приложений, оставляя границы фреймворка с помощью Classes to exclude. Поддерживаются три вида правил:

com.example.SecretService   Соответствует только этому классу
com.example.service.*       Соответствует текущей папке, без вложенных папок
com.example.service.**      Соответствует текущей папке и всем вложенным папкам

Возможно выбор из дерева классов с использованием Choose…, а также ручное добавление правил через Add…. По умолчанию выбор пакетов позволяет охватить текущий пакет и все его подпакеты; для исключения только текущего пакета используется .*. В дереве классов Spring Boot также отображаются зависимости JAR, для которых выбрана защита.

Рекомендуемая структура — “Публичный граница/вход в фреймворк → обычный фасад или интерфейс → защищённое приложение”. Не стоит шифровать все сторонние зависимости или точки входа в фреймворки ради расширения области защиты.

8. Экспорт, повторное использование и окончательная проверка

Нажатие на Export parameters… позволяет экспортировать:

• p4j-encrypt-run.sh
• p4j-encrypt-run.bat

Скрипт экспорта сохраняет текущие настроки, но не включает адрес электронной почты и пароль пользователя. Позже задание можно восстановить с помощью элемента Load Task File, расположенного в верхней части интерфейса.

После перехода на страницу вывода необходимо проверить по меньшей мере следующие пункты:

• Укажите имя файла, тип приложения, версию Java и все целевые платформы;
• Приставки архивации, параметры JIT, элементы отображения сканера и настройки JVM;
• JavaFX/WebView, структура разметки Spring Boot или версия/context Tomcat;
• Защищённые зависимости в формате JAR и все правила исключения;
• Каталог вывода, а также информация о необходимости создания нового подкаталога p4jx-xxxx.

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