Einstellungen für den Fortgeschrittenen Modus von Protector4J

Der Fortgeschrittene Modus dient dazu, den Schutzumfang, die Kompatibilitätsoptionen sowie spezielle Parameter für bestimmte Anwendungsarten manuell festzulegen. Beim Erstverarbeiten einer neuen Anwendung wird empfohlen, zunächst den Einfachmodus zu verwenden oder eine Kompatibilitätsprüfung auf der Seite mit den fortgeschrittenen Parametern durchzuführen, um anschließend entsprechend den Ergebnissen anzupassen.

Dieser Text ist eine ausführlichere Erklärung zum Fortgeschrittenen Modus in GUI-Benutzerhandbuch. Wenn entschieden werden muss, welche Klassen unverschlüsselt bleiben sollen, sollte Kompatibilitätsprüfung und Schutzumfang zurate gezogen werden; bei der Erstellung automatisierter Befehle gilt Referenz für CLI-Parameter als Referenz.

1. Zum Fortgeschrittenen Modus wechseln

1. Anwendungsart auswählen und JAR/WAR eingeben.
2. Die mitgelieferte Java-Version sowie mindestens eine Zielplattform auswählen.
3. In Mode Advanced — customise the options yourself auswählen.
4. Auf Next klicken, um zur Seite mit den fortgeschrittenen Parametern zu gelangen.

Falls Sie bereits auf der Bestätigungsseite für die Ausgabe sind, können Sie auf Customize… klicken, um zur Seite mit den fortgeschrittenen Parametern zurückzukehren. Nach den Änderungen gehen Sie erneut zur Ausgabeseite, um sicherzustellen, dass der Zusammenfassung die neuen Einstellungen widergespiegelt werden.

Die Java-Version und die Zielplattform werden nicht auf der Seite mit den fortgeschrittenen Parametern geändert; falls Anpassungen notwendig sind, kehren Sie zur Eingabeseite zurück. Mehrplattformsaufgaben erzeugen für jede Plattform eine eigene Ausgabe, wobei vlxjre nicht ausgetauscht werden darf.

2. Allgemeine Optionen

Vier Anwendertypen teilen sich den Bereich mit den fortgeschrittenen Parametern, doch einige Einstellungen gelten je nach Typ. Library Encryption erzeugt keinen Startskript, weshalb keine JVM-Startparameter verwendet werden; die Einstellung für das Archivierungs-Suffix dient dazu, Vorschläge für die Ausgabenamen zu erstellen und diese zu synchronisieren.

Die tatsächlich vorhandenen speziellen Einstellungen für verschiedene Anwendungstypen sind wie folgt:

“Es wird kein Schutz gegen solche Fälle vorgesehen.” bedeutet, dass standardmäßig alle Anwendungsarten dieses Typs geschützt werden, was jedoch nicht bedeutet, dass auch externe Abhängigkeiten mitgeschützt werden. BOOT-INF/lib von Spring Boot sowie WEB-INF/lib von Tomcat bleiben standardmäßig im normalen Zustand.

Archiv-Endung

Die Auswahl von jar ändert lediglich den Dateinamen; der Inhalt der Datei bleibt im P4JX-Format. Sie kann weder mit herkömmlichen ZIP/JAR-Tools geändert noch mit einem normalen JRE geladen werden. Bei Library Encryption wechselt diese Einstellung die Endung der ausgewählten Ausgabedatei auf .p4jx/.jar; falls der Benutzer eine andere benutzerdefinierte Endung angegeben hat, bleibt der vollständige Dateinamen erhalten.

Zugehörige CLI:

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

Verbot der JIT-Schutzmethode

Durch Aktivierung von Disable JIT for protected methods werden geschützte Methoden nicht dem JIT-Kompilator zugeführt, wodurch die Offenheit des kompilierten Maschinencode verringert werden kann. Allerdings kann codeintensiver Code deutlich langsamer werden. Diese Einstellung betrifft nur geschützte Methoden und wechselt den gesamten JVM nicht in einen rein interpretierten Modus.

Zugehörige CLI:

--no-jit

Scanner ZIP overlay

„overlay“ gibt nur öffentliche Ressourcen, Verzeichnisse sowie Metadaten der Schutzklasse preis und enthält keine tatsächlichen Methodenkörper. Es dient der Kompatibilität mit Tools, die das zentrale Verzeichnis eines ZIP-Archivs direkt lesen, kann jedoch die Layout-Struktur von Spring Boot fat nicht ersetzen und löst auch nicht das Problem der Parsing von Archiven mithilfe von ZipInputStream/JarInputStream aus einem Memory Stream.

Zugehörige CLI:

--zip-overlay scanner

JVM-Startparameter

Tragen Sie pro Zeile einen vollständigen Parameter ein, z. B.:

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

Jede Zeile stellt eine Parametergrenze dar – schreiben Sie keine mehreren Parameter in derselben Zeile. Die Parameter werden in die Startskripte für macOS/Linux und Windows geschrieben; auch die Tomcat-Parameter werden in dessen Startpfad aufgenommen. Bei „Library Encryption“ werden keine Startskripte erzeugt, weshalb das Eingabefeld nicht verfügbar ist. Vollständigere Beispiele für verschiedene Plattformen finden Sie unter Konfiguration der JVM-Startparameter.

Die zugehörige CLI erfordert die wiederholte Verwendung von Optionen:

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

3. Kompatibilitätsprüfung und Anwendungsempfehlungen

Für alle vier Anwendungstypen kann man auf Compatibility scan… klicken, um die aktuelle Eingabe zu scannen. Bei Annahme der Ergebnisse fügt das Tool die für diesen Anwendungstyp empfohlenen Einstellungen zu den aktuellen Einstellungen hinzu, hauptsächlich umfassend:

• Hinzufügen von Klassen, die unverschlüsselt bleiben müssen;
• Aktivierung des Scanner ZIP overlay;
• Anpassung des Archiv-Endungsnamens;
• Aktivierung von JavaFX/WebView für Java Application oder Spring Boot;
• Auswahl des Layouts für Spring Boot;
• Auswahl von 9 oder 10.1 für Tomcat.

Die Library Encryption wendet automatisch nur die Empfehlungen bezüglich des Scanner ZIP overlay sowie des Archiv-Endungsnamens an. Sie schützt per Design alle Klassen im Eingabes JAR und unterstützt keine Ausnahmen für bestimmte Klassen; falls beim Scannen Inhalte wie JNI-/Nativklassen entdeckt werden, die unverschlüsselt bleiben müssen, wird ausdrücklich empfohlen, diese in ein normales JAR auszulagern oder einen Paketierungsmodus zu verwenden, der eine selektive Schutzfunktion ermöglicht.

Nach Annahme der Empfehlungen kann weiterhin bearbeitet werden. Der Scan behält bestehende Ausschlussregeln bei und schaltet das von dem Benutzer aktivierte JavaFX nicht automatisch aus, falls JavaFX nicht erkannt wird. Durch Verwerfen des Dialogfelds werden die Empfehlungen nicht angewendet.

Die auf Code-Ebene im Scanbericht festgestellten Risiken – wie z. B. Agenten, JNI, benutzerdefinierte Class-Loader oder Änderungen am Laufzeit-Bytecode – lassen sich in der Regel nicht allein mit einem Schalter beheben. Es sollten die Code-Grenzen gemäß Kompatibilitätsprüfung und Schutzumfang angepasst und eine praktische Überprüfung durchgeführt werden.

4. Einstellungen für Java Application

Main class

Wird leer gelassen, wird Main-Class zur Auswertung des Eingabes JAR Manifests verwendet. Nur dann sollte der vollständige Klassennamen eingegeben werden, wenn im Manifest keine Hauptklasse vorhanden ist oder eine andere Standard-Startklasse überschrieben werden muss – beispielsweise com.example.Main.

Entspricht der CLI: --main com.example.Main.

Classes to exclude

Standardmäßig werden alle Anwendungsklassen geschützt. Klassen oder Pakete in dieser Liste bleiben unverschlüsselt und eignen sich für DTOs, Entitäten, Konfigurationsklassen, JNI-Brückenklassen sowie Klassen, die von Frameworks erweitert oder deren echter Bytecode gelesen werden muss. Die Formatregeln finden Sie unter “Schutzumfang und Ausschlussregeln”.

JavaFX runtime

Für herkömmliche JavaFX-Anwendungen sollte Bundle JavaFX into the packaged runtime ausgewählt werden. Für WebView steht folgende Auswahl zur Verfügung:

• Auto: Enthält den Inhalt, wenn javafx.scene.web erkannt wird;
• Include: Zwingende Einbeziehung von fx-webkit;
• Exclude: Muss ausgeschlossen werden.

WebView fügt etwa 40 MB hinzu. Die GUI lädt Ressourcen für die Ziel-Java-Version und Plattform herunter; bei der Verwendung der CLI muss ein lokaler, offline verfügbarer JavaFX-Ordner angegeben werden.

Zugehörige CLI: --javafx, --javafx-webview und --no-javafx-webview. Auto schreibt keine zusätzlichen Optionen für WebView hinzu – der Paketierer entscheidet dies basierend auf den Referenzen der Anwendung.

5. Spring Boot-Einstellungen

Main class

Wenn dieses Feld leer gelassen wird, wird Start-Class zur Auswertung des Manifests verwendet. Bei der Notwendigkeit, die Startklasse zu überschreiben, muss der vollständige Klassennamen eingegeben werden.

Zugehörige CLI: --main com.example.Application.

Layout

Falls die Kompatibilitätsprüfung ausdrücklich fat empfiehlt, sollte man nicht nur den ZIP-overlay aktivieren und dennoch darauf bestehen, p4jx-fat zu verwenden. Weitere Details zur Anordnung finden Sie in Schutz für Spring Boot-Anwendungen.

Zugehörige CLI-Optionen: --layout p4jx-fat, --layout fat oder --layout separate.

Protect dependency JARs…

Die Abhängigkeiten in BOOT-INF/lib sind standardmäßig nicht geschützt. Markieren Sie nur eigene, proprietäre Abhängigkeiten; verschlüsseln Sie keine Pakete von Drittanbieter-Frameworks wie Spring, Tomcat, Logging-Tools oder Datenbank-Treiber. Signierte JAR-Dateien werden als nicht wählbar angezeigt, da Änderungen ihre Signatur zerstören würden.

Wenn eine Abhängigkeit markiert wird, werden alle darin enthaltenen Klassen geschützt, doch die Regeln von Classes to exclude ermöglichen es weiterhin, bestimmte Klassen oder Pakete für diese Abhängigkeit auszuschließen. Alle drei Spring Boot-Anordnungen unterstützen den Schutz von Abhängigkeiten.

Zugehörige CLI-Option: --protect-lib 'company-core.jar,company-domain.jar'. Die CLI unterstützt außerdem glob-Suchmuster; die GUI speichert den genauen Dateinamen des ausgewählten JARs.

Klassen, die ausgeschlossen werden, und JavaFX

Die Verwendung ist identisch mit einer Java-Anwendung. Die Ausschlussregeln gelten sowohl für Anwendungsklassen als auch für die ausgewählten, geschützten Abhängigkeits-JARs. Spring Boot + JavaFX-Desktopanwendungen können ebenfalls unter der Registerkarte JavaFX runtime mit JavaFX/WebView verpackt werden.

6. Einstellungen für Tomcat

Tomcat version

• Verwenden Sie für das WAR von javax.servlet.* Tomcat 9 · javax;
• Verwenden Sie für das WAR von jakarta.servlet.* Tomcat 10.1 · jakarta.

Für Tomcat 10.1 ist mindestens Java 11 erforderlich. Führen Sie bei Unsicherheit eine Kompatibilitätsprüfung durch; wenn die Anwendung sowohl javax als auch jakarta verwendet, wählen Sie keine Version erzwungen aus, sondern beheben Sie zuerst Konflikte in den Abhängigkeiten.

Im fortgeschrittenen Modus gibt es keine voreingestellte Version – man muss entweder die Vorschläge der Scan-Tools akzeptieren oder eine Version manuell auswählen, um zum nächsten Schritt zu gelangen. Entsprechende CLI-Optionen: --tomcat-version 9 oder --tomcat-version 10; die CLI erlaubt außerdem auto.

Context path

Geben Sie den Deployment-Pfad ein, der mit / beginnt, z. B. /app. Wenn dieser leer gelassen wird, wird /app verwendet. Wenn die Anwendung in einen bestehenden Ausgabekatalog von Tomcat hinzugefügt wird, darf der Context-Path nicht mit bereits vorhandenen Anwendungen übereinstimmen.

Zugehörige CLI: --context /app.

Classes to exclude

Standardmäßig wird die Klassengruppe unter WEB-INF/classes geschützt, während Abhängigkeiten wie WEB-INF/lib standardmäßig ungeschützt bleiben. In der Regel sollten Servlets, Filter, Listener, DTOs, Konfigurationen, Entitäten, JNI-Brückenklassen sowie Klassen, die vom Container erweitert werden müssen, ausgeschlossen werden.

7. Schutzumfang und Ausschlussregeln

Im Hochleistungsmodus schützt die GUI standardmäßig alle Anwendungsarten, wobei die Rahmengrenzen mithilfe von Classes to exclude festgelegt werden. Es stehen drei Regeln zur Verfügung:

com.example.SecretService   Erstellt nur eine Übereinstimmung für diese Klasse
com.example.service.*       Überprüft den aktuellen Paketinhalt, ausschließlich ohne Unterpakete
com.example.service.**      Überprüft den aktuellen Paketinhalt sowie alle Unterpakete

Es ist möglich, über Choose… aus dem Klassentree auszuwählen, oder man kann Elemente manuell hinzufügen mithilfe von Add…. Die Paketauswahl umfasst standardmäßig das aktuelle Paket sowie seine Unterpakete; falls nur das aktuelle Paket ausgeschlossen werden soll, wird .* verwendet. Der Klassentree von Spring Boot zeigt außerdem die ausgewählten, geschützten Abhängigkeits-JARs an.

Die empfohlene Struktur ist “Öffentliche Grenze/Rahmen-Eingang → gewöhnliche Facade oder Schnittstelle → geschützte Kernimplementierung”. Versuchen Sie nicht, den Schutzumfang zu erweitern, indem Sie alle Drittanbieter-Abhängigkeiten oder Framework-Eintritte verschlüsseln.

8. Exportieren, Wiederverwenden und abschließende Überprüfung

Durch Klicken auf Export parameters… kann exportiert werden:

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

Die Exportskripte speichern die derzeit konfigurierten Einstellungen, schreiben jedoch weder E-Mail-Adresse noch Passwort ab. Später kann die Aufgabe über Load Task File an der Oberseite wiederhergestellt werden.

Nach dem Betreten der Ausgabeseite sollten zumindest die folgenden Elemente überprüft werden:

• Geben Sie die Eingabedatei, die Anwendungsart, die Java-Version sowie alle Zielplattformen ein.
• Archivierungsendung, JIT, Scanner-Overlay sowie JVM-Parameter;
• JavaFX/WebView, Spring Boot-Layout oder Tomcat-Version/context;
• geschützte Abhängigkeits-JARs sowie alle Ausschlussregeln;
• Ausgabeverzeichnis sowie ob ein neues Unterverzeichnis p4jx-xxxx erstellt werden soll.

Nach der Erstellung müssen auf jeder Zielplattform die im Paket enthaltenen Startskripte zur Überprüfung von Startvorgängen, Framework-Scans, Serialisierung, Reflexion, Ressourcenzugriffen sowie den Kerngeschäftsabläufen verwendet werden. Eine korrekte Konfiguration der fortgeschrittenen Parameterseite zeigt lediglich an, dass die Aufgabeparameter eingestellt wurden, ersetzt aber nicht die Überprüfung des endgültigen Produkts.