Configuración del modo avanzado de Protector4J

El modo avanzado permite decidir manualmente el alcance de protección, las opciones de análisis de compatibilidad y los parámetros específicos para cada tipo de aplicación protegida. Al tratar una nueva aplicación por primera vez, se recomienda utilizar primero el modo simple o ejecutar un escaneo de compatibilidad en la página de parámetros avanzados, y luego ajustar según los resultados del escaneo.

Este documento explica en detalle el modo avanzado de Guía de uso de la GUI. Para determinar qué clases deben permanecer sin cifrar, consulte Compatibilidad y alcance de protección; si necesita escribir comandos automatizados, siga las indicaciones de Referencia de parámetros de la CLI.

1. Entrar al modo avanzado

1. Elegir el tipo de aplicación protegida e ingresar JAR/WAR.
2. Seleccionar Versión de Java incluida en el paquete y al menos una plataforma de destino.
3. Elegir Advanced — customise the options yourself dentro de Mode.
4. Hacer clic en Next para acceder a la página de parámetros avanzados.

Si ya se está en la página de confirmación de salida, se puede hacer clic en Customize… para volver a la página de parámetros avanzados. Después de realizar los cambios, vuelva a la página de salida para confirmar que el resumen refleje la nueva configuración.

La versión de Java y la plataforma de destino no se modifican en la página de parámetros avanzados; si es necesario ajustarlos, hay que volver a la página de entrada. Las tareas multiplataforma generan una salida independiente para cada plataforma, y los elementos vlxjre no pueden intercambiarse entre ellas.

2. Opciones generales

Los cuatro tipos de aplicaciones comparten la sección de parámetros avanzados, pero algunos ajustes solo son efectivos según el tipo. Library Encryption no genera un script de inicio, por lo que no se utilizan parámetros de inicio de JVM; su configuración de sufijo de archivo se usa para sugerir y sincronizar los nombres de los archivos de salida.

Los ajustes específicos que aparecen realmente para cada tipo de aplicación son los siguientes:

“No se descarta la clase.” significa que, por defecto, se brinda protección a todos los tipos de aplicaciones de ese tipo, pero esto no implica que también se protejan las dependencias de terceros. BOOT-INF/lib en Spring Boot y WEB-INF/lib en Tomcat permanecen en estado normal por defecto.

Sufijo de archivado

Al seleccionar jar, solo cambia el nombre del archivo; su contenido sigue siendo en formato P4JX. No se puede modificar con herramientas comunes de ZIP/JAR, ni se puede cargar con un JRE estándar. En el caso de Library Encryption, esta configuración cambia el sufijo del archivo de salida a .p4jx/.jar; si el usuario especifica otro sufijo personalizado, se mantiene el nombre completo del archivo.

CLI correspondiente:

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

Prohibir el método de protección JIT

Al activar Disable JIT for protected methods, los métodos protegidos no pasan por el compilador JIT, lo que reduce la superficie expuesta del código máquina generado, aunque el código intensivo en cálculos podría ralentizarse significativamente. Esta configuración solo afecta a los métodos protegidos y no cambia todo el JVM a un modo puramente interpretativo.

CLI correspondiente:

--no-jit

Superposición ZIP del escáner

overlay solo expone metadatos de recursos públicos, directorios y clases de protección, sin incluir el cuerpo real de los métodos. Se utiliza para ser compatible con herramientas que leen directamente el directorio central de ZIP, pero no puede reemplazar la configuración de Spring Boot fat, ni resolver escenarios en los que se analizan archivos comprimidos desde flujos de memoria utilizando ZipInputStream/JarInputStream.

CLI correspondiente:

--zip-overlay scanner

Parámetros de inicio de JVM

Introduzca un parámetro completo en cada línea, por ejemplo:

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

Cada línea marca el límite de un parámetro; no escriba varios parámetros en la misma línea. Los parámetros se escribirán en los scripts de inicio para macOS/Linux y Windows; los parámetros de Tomcat también se incluirán en su ruta de inicio. Library Encryption no genera scripts de inicio, por lo que el cuadro de entrada está desactivado. Para ejemplos más completos por plataforma, consulte Configuración de parámetros de inicio de JVM.

El CLI correspondiente requiere usar repetidamente ciertas opciones:

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

3. Análisis de compatibilidad y recomendaciones para aplicaciones

Para los cuatro tipos de aplicaciones, se puede hacer clic en Compatibility scan… para escanear la entrada actual. Al aceptar los resultados, la herramienta integrará las recomendaciones relevantes para ese tipo de aplicación en la configuración actual, que incluyen principalmente:

• Añadir clases que deben permanecer sin cifrar;
• Habilitar la capa ZIP overlay del escáner;
• Ajustar el sufijo de archivo para los archivos comprimidos;
• Habilitar JavaFX/WebView para aplicaciones Java o Spring Boot;
• Elegir el diseño de interfaz para Spring Boot;
• Elegir la versión 9 o 10.1 para Tomcat.

La función Library Encryption solo aplica automáticamente las sugerencias relacionadas con la capa ZIP overlay del escáner y los sufijos de archivo. Está diseñada para proteger todas las clases del JAR de entrada, sin soporte para la exclusión de clases; si el escaneo detecta contenido que debe permanecer sin cifrar, como clases JNI/nativas, el informe indicará claramente que es necesario moverlo a un JAR normal o utilizar un modo de empaquetado de aplicación que permita una protección selectiva.

Se puede seguir editando después de aceptar las sugerencias. El escaneo mantendrá las reglas de exclusión existentes y no desactivará automáticamente JavaFX si no se detecta su presencia. Al cancelar el diálogo, las sugerencias no se aplicarán.

Los riesgos a nivel de código presentes en los informes de escaneo, como Agent, JNI, cargadores de clases personalizados o reescritura de bytecode en tiempo de ejecución, generalmente no pueden resolverse únicamente con un interruptor. Es necesario ajustar los límites del código según Compatibilidad y alcance de protección y realizar pruebas prácticas.

4. Configuración de la aplicación Java

Main class

Main-Class: se lee el Manifest del JAR de entrada cuando este campo está vacío. Solo se debe ingresar el nombre completo de la clase cuando el Manifest carezca de una clase principal o sea necesario sobrescribir la clase de inicio predeterminada, por ejemplo, com.example.Main.

CLI correspondiente: --main com.example.Main.

Classes to exclude

Por defecto, todas las clases de la aplicación están protegidas. Las clases o paquetes en esta lista permanecen sin cifrar y son adecuados para DTO, entidades, clases de configuración, clases de enlace JNI y aquellas que necesitan ser mejoradas por el framework o leer su bytecode real. El formato de las reglas se encuentra en “Alcance de protección y reglas de exclusión”.

JavaFX runtime

Para aplicaciones JavaFX comunes, seleccione Bundle JavaFX into the packaged runtime. Para WebView, se puede elegir:

• Auto: se incluye cuando se detecta javafx.scene.web;
• Include: se incluye obligatoriamente fx-webkit;
• Exclude: Debe excluirse obligatoriamente.

WebView aumentará el tamaño en aproximadamente 40 MB. La interfaz gráfica descargará los recursos según la versión y plataforma de Java objetivo; se debe utilizar la CLI cuando sea necesario especificar un directorio local offline para JavaFX.

CLI correspondiente: --javafx, --javafx-webview y --no-javafx-webview. Auto no escribe opciones obligatorias para WebView; el empaquetador decide según las referencias de la aplicación.

5. Configuración de Spring Boot

Main class

Si se deja en blanco, se leerá Start-Class del Manifest. Se debe ingresar el nombre completo de la clase si es necesario sobrescribir la clase de inicio.

CLI correspondiente: --main com.example.Application.

Layout

Si el análisis de compatibilidad recomienda explícitamente fat, no fuerce el uso de p4jx-fat después de activar solo el ZIP overlay. Para más detalles sobre la configuración, consulte Protección de aplicaciones Spring Boot.

CLI correspondiente: --layout p4jx-fat, --layout fat o --layout separate.

Protect dependency JARs…

Por defecto, las dependencias en BOOT-INF/lib no están protegidas. Solo seleccione las dependencias propias de código cerrado; no encripte paquetes de frameworks de terceros como Spring, Tomcat, sistemas de registro o controladores de base de datos. Los JAR firmados se mostrarán como no seleccionables, ya que cualquier modificación dañaría su firma.

Al seleccionar una dependencia, todas sus clases quedarán protegidas, pero las reglas de Classes to exclude aún permiten excluir clases o paquetes específicos de dicha dependencia. Los tres diseños de Spring Boot admiten la protección de dependencias.

CLI correspondiente: --protect-lib 'company-core.jar,company-domain.jar'. La CLI también soporta expresiones globales; la GUI guarda el nombre exacto del archivo del JAR seleccionado.

Clases a excluir y JavaFX

El uso es el mismo que en una aplicación Java. Las reglas de exclusión se aplican tanto a las clases de la aplicación como a los JAR de dependencias seleccionados para su protección. Las aplicaciones de escritorio Spring Boot + JavaFX también pueden empacar JavaFX/WebView en la pestaña JavaFX runtime.

6. Configuración de Tomcat

Tomcat version

• Utilice javax.servlet.* para seleccionar Tomcat 9 · javax con un WAR;
• Utilice jakarta.servlet.* para seleccionar Tomcat 10.1 · jakarta con un WAR.

Tomcat 10.1 requiere al menos Java 11. Si no está seguro, ejecute un análisis de compatibilidad; si la aplicación utiliza tanto javax como jakarta, no elija forzadamente una versión, sino que primero resuelva los conflictos de dependencias.

El modo avanzado no tiene una versión preseleccionada; es necesario aceptar las recomendaciones del análisis o seleccionar manualmente antes de pasar al siguiente paso. CLI correspondiente: --tomcat-version 9 o --tomcat-version 10; la CLI también permite auto.

Context path

Rellene la ruta de despliegue que comienza con /, por ejemplo, /app. Si se deja en blanco, se utilizará /app. Al agregar una aplicación al directorio de salida existente de Tomcat, la ruta de contexto no puede coincidir con ninguna aplicación ya existente.

CLI correspondiente: --context /app.

Classes to exclude

Por defecto, protege las aplicaciones de la categoría WEB-INF/classes; WEB-INF/lib no está protegido por defecto. Por lo general, se deben excluir las clases Servlet, Filter, Listener, DTO, configuraciones, entidades, clases de enlace JNI y aquellas que requieren mejoras en el contenedor.

7. Ámbito de protección y reglas de exclusión

En el modo avanzado, la GUI ofrece protección predeterminada para todas las clases de aplicaciones, dejando los límites del marco definidos por Classes to exclude. Se admiten tres tipos de reglas:

com.example.SecretService   Solo coincide con esta clase
com.example.service.*       Coincide con el paquete actual, sin incluir subpaquetes
com.example.service.**      Coincide con el paquete actual y todos sus subpaquetes

Se puede seleccionar desde el árbol de clases mediante Choose…, o bien agregar reglas manualmente con Add…. La selección de paquetes cubre de forma predeterminada el paquete actual y sus subpaquetes; use .* si solo se desea excluir el paquete actual. El árbol de clases de Spring Boot también muestra los JAR de dependencias que han sido seleccionados para protección.

La estructura recomendada es “Entrada de borde/framwork público → Facade o interfaz común → Implementación central protegida”. No cifre todas las dependencias de terceros ni los puntos de entrada de los frameworks con el fin de ampliar el alcance de protección.

8. Exportación, reutilización y revisión final

Al hacer clic en Export parameters…, se pueden exportar los datos:

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

El script de exportación guarda las opciones analizadas actualmente, pero no incluye la dirección de correo ni la contraseña del usuario. Posteriormente, se puede restaurar la tarea mediante Load Task File en la parte superior.

Una vez en la página de resultados, revise al menos los siguientes elementos:

• Incorpore el archivo de entrada, el tipo de aplicación, la versión de Java y todas las plataformas de destino.
• Sufijos de archivo, JIT, overlay del escáner y parámetros de JVM;
• JavaFX/WebView, configuración de layout de Spring Boot o versión/contexto de Tomcat;
• Los JAR dependientes protegidos y todas las reglas de exclusión;
• El directorio de salida y si se debe crear un subdirectorio nuevo p4jx-xxxx.

Después de la generación, es necesario utilizar los scripts de inicio dentro del paquete en cada plataforma objetivo para verificar el inicio, el escaneo del framework, la serialización, el reflejo, la carga de recursos y las rutas de negocio principales. Una configuración correcta en la página de parámetros avanzados solo indica que los parámetros de la tarea se han establecido, pero no sustituye la verificación del producto final.