Ajustes del modo avanzado de Protector4J

El modo avanzado permite fijar a mano el alcance de la protección, las opciones de compatibilidad y las opciones propias de cada tipo de aplicación. La primera vez que trate una aplicación nueva, empiece en el modo simple o ejecute un escaneo de compatibilidad en la página de opciones avanzadas y ajuste a partir de su resultado.

Esta página amplía el apartado sobre el modo avanzado de la Guía de la interfaz gráfica. Para decidir qué clases dejar sin proteger, consulte Compatibilidad y alcance de la protección; para escribir el comando automatizado equivalente, la Referencia de la línea de comandos.

1. Entrar en el modo avanzado

1. Elija el tipo de aplicación y el JAR o WAR de entrada.
2. Elija la versión de Java que se incluirá y al menos una plataforma de destino.
3. En Modo, seleccione Avanzado — personalice las opciones usted mismo.
4. Haga clic en Siguiente para abrir la página de opciones avanzadas.

Si ya está en la página de revisión de la salida, haga clic en Personalizar... para volver a las opciones avanzadas. Tras los cambios, regrese a la página de salida y compruebe que el resumen los recoge.

La versión de Java y las plataformas de destino no pueden cambiarse en la página de opciones avanzadas; para ello vuelva a la página de entrada. Una tarea con varias plataformas produce una salida independiente por plataforma, y sus directorios vlxjre no son intercambiables.

2. Opciones comunes

Los cuatro tipos de aplicación comparten esta sección, aunque algunos ajustes solo se aplican a determinados tipos. El cifrado de bibliotecas no genera scripts de arranque, así que no tiene opciones de inicio de la JVM; su ajuste de sufijo sirve para proponer y mantener coherente el nombre del archivo de salida.

Las opciones propias de cada tipo:

«Sin exclusiones» significa que se protegen todas las clases de aplicación de ese tipo. No significa que también se protejan las dependencias de terceros: BOOT-INF/lib en Spring Boot y WEB-INF/lib en Tomcat quedan fuera de la protección de forma predeterminada.

Sufijo del archivo

Elegir jar solo cambia el nombre; el contenido sigue siendo P4JX. No puede abrirse con herramientas ZIP o JAR corrientes ni cargarse con un JRE estándar. En el cifrado de bibliotecas, este ajuste alterna el sufijo del archivo de salida entre .p4jx y .jar; si escribe usted otro sufijo, se respeta el nombre que haya puesto.

Opción equivalente:

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

Desactivar JIT para métodos protegidos

Desactivar JIT para métodos protegidos mantiene esos métodos fuera del compilador JIT, con lo que se expone menos código máquina compilado. Puede ralentizar bastante el código con mucho cálculo. Solo afecta a los métodos protegidos y no pone toda la JVM en modo interpretado.

Opción equivalente:

--no-jit

Capa ZIP para escáneres

La capa expone únicamente recursos públicos, directorios y los esbozos de metadatos de las clases protegidas; nunca los cuerpos reales de los métodos. Existe para que sigan funcionando las herramientas que leen directamente el directorio central del ZIP. No sustituye al diseño fat de Spring Boot y no sirve cuando el archivo se analiza desde un flujo en memoria con ZipInputStream o JarInputStream.

Opción equivalente:

--zip-overlay scanner

Opciones de inicio de la JVM

Escriba una opción completa por línea, por ejemplo:

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

Cada línea es una opción: nunca ponga dos en la misma. Las opciones se escriben en los scripts de arranque de macOS, Linux y Windows, y en Tomcat también en su ruta de arranque. El cifrado de bibliotecas no genera scripts de arranque, así que allí el campo está desactivado. Hay ejemplos más completos por plataforma en Opciones de inicio de la JVM.

En la línea de comandos, la opción se repite:

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

3. El escaneo de compatibilidad y sus recomendaciones

En los cuatro tipos, Escaneo de compatibilidad... analiza la entrada actual. Si acepta el resultado, la herramienta incorpora a sus ajustes las recomendaciones propias de ese tipo, sobre todo:

• añadir clases que deberían quedar sin proteger;
• activar la capa ZIP para escáneres;
• ajustar el sufijo del archivo;
• activar JavaFX y WebView en una aplicación Java o en Spring Boot;
• elegir el diseño para Spring Boot;
• elegir Tomcat 9 o 10.1.

El cifrado de bibliotecas solo aplica las recomendaciones de capa ZIP y sufijo. Está pensado para proteger todas las clases del JAR de entrada y no admite exclusiones, así que si el escaneo encuentra algo que debe quedar sin proteger —clases JNI o nativas, por ejemplo—, el informe le indica que las traslade a un JAR corriente o que cambie a un modo de empaquetado con protección selectiva.

Después de aceptar las recomendaciones puede seguir editando. El escaneo conserva las reglas de exclusión que ya tuviera y no desactiva un JavaFX que usted haya activado solo porque no lo haya detectado. Si cancela el cuadro de diálogo, no se aplica nada.

Los riesgos a nivel de código que aparecen en el informe —agentes, JNI, cargadores de clases propios, bytecode modificado en tiempo de ejecución— no suelen resolverse cambiando un ajuste. Use Compatibilidad y alcance de la protección para reubicar las fronteras de su código y pruébelo de verdad.

4. Opciones de la aplicación Java

Clase principal

Si se deja vacío, la Main-Class se lee del manifiesto del JAR de entrada. Escriba un nombre de clase completo solo si el manifiesto no tiene clase principal o si quiere sustituirla, por ejemplo com.example.Main.

Opción equivalente: --main com.example.Main.

Clases para excluir

De forma predeterminada se protege toda clase de la aplicación. Las clases y paquetes de esta lista quedan sin proteger, lo que conviene a DTO, entidades, clases de configuración, clases puente de JNI y a todo lo que amplíe un framework o que necesite leer su propio bytecode real. La sintaxis se explica más abajo, en «Alcance de la protección y reglas de exclusión».

Entorno de ejecución JavaFX

En una aplicación JavaFX sencilla, marque Incluir JavaFX en el runtime empaquetado. Para WebView hay tres opciones:

• Automático (detectar javafx.scene.web): se incluye solo si se detecta javafx.scene.web;
• Incluir: incorpora siempre fx-webkit;
• Excluir: no lo incorpora nunca.

WebView añade unos 40 MB. La interfaz descarga los componentes correspondientes a su versión de Java y plataforma de destino; si necesita indicar un directorio local de JavaFX, use la línea de comandos.

Opciones equivalentes: --javafx, --javafx-webview, --no-javafx-webview. Automático no tiene opción propia, porque lo decide el empaquetador a partir de las referencias de la propia aplicación.

5. Opciones de Spring Boot

Clase principal

Si se deja vacío, Start-Class se lee del manifiesto. Escriba un nombre de clase completo para sustituirla.

Opción equivalente: --main com.example.Application.

Diseño

Si el escaneo recomienda claramente fat, no fuerce p4jx-fat confiando en que la capa ZIP lo compense. Los detalles de cada diseño están en Proteger aplicaciones Spring Boot.

Opciones equivalentes: --layout p4jx-fat, --layout fat, --layout separate.

Proteger los JAR de dependencias…

Las dependencias de BOOT-INF/lib no se protegen de forma predeterminada. Elija solo sus propias dependencias de código cerrado; no cifre paquetes de frameworks de terceros como Spring, Tomcat, bibliotecas de registro o controladores de base de datos. Los JAR firmados no pueden seleccionarse, porque modificarlos rompería su firma.

Al elegir una dependencia se protegen todas sus clases, aunque puede usar Clases para excluir para dejar sin proteger clases o paquetes concretos de su interior. Los tres diseños de Spring Boot admiten la protección de dependencias.

Opción equivalente: --protect-lib 'company-core.jar,company-domain.jar'. La línea de comandos acepta además patrones glob; la interfaz registra los nombres exactos de los JAR seleccionados.

Clases para excluir y JavaFX

Funcionan igual 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 dependencia elegidos para proteger. Una aplicación de escritorio Spring Boot también puede incluir JavaFX y WebView desde la pestaña Entorno de ejecución JavaFX.

6. Opciones de Tomcat

Versión de Tomcat

• Si el WAR usa javax.servlet.*, elija Tomcat 9 · javax.
• Si usa jakarta.servlet.*, elija Tomcat 10.1 · jakarta.

Tomcat 10.1 requiere Java 11 o posterior. Ejecute un escaneo de compatibilidad si tiene dudas. Si la aplicación usa a la vez javax y jakarta, no fuerce una versión: resuelva antes el conflicto de dependencias.

El modo avanzado no preselecciona ninguna versión: hay que aceptar la recomendación del escaneo o elegir una a mano para continuar. Opciones equivalentes: --tomcat-version 9 o --tomcat-version 10; la línea de comandos acepta además auto.

Ruta de contexto

Escriba la ruta de despliegue empezando por /, por ejemplo /app. Si se deja vacía se usa /app. Al añadir una aplicación a un directorio de salida de Tomcat existente, la ruta no debe coincidir con la de otra aplicación.

Opción equivalente: --context /app.

Clases para excluir

De forma predeterminada se protegen las clases de aplicación bajo WEB-INF/classes, y WEB-INF/lib queda fuera. Servlets, filtros, escuchadores, DTO, clases de configuración, entidades, clases puente de JNI y todo lo que el contenedor deba ampliar suelen ir excluidos.

7. Alcance de la protección y reglas de exclusión

En el modo avanzado, la interfaz protege de forma predeterminada todas las clases de la aplicación, y la frontera con el framework se traza con Clases para excluir. Hay tres formas de regla:

com.example.SecretService   solo esta clase
com.example.service.*       solo este paquete, sin subpaquetes
com.example.service.**      este paquete y todos sus subpaquetes

Puede elegir clases del árbol con Elegir... o escribirlas con Añadir.... Seleccionar un paquete abarca por defecto también sus subpaquetes; con .* lo limita al paquete en sí. En Spring Boot, el árbol muestra además los JAR de dependencia elegidos para proteger.

La disposición recomendada es: frontera pública o entrada del framework → fachada o interfaz corriente → implementación principal protegida. No cifre todas las dependencias de terceros y los puntos de entrada del framework solo para que la superficie protegida parezca mayor.

8. Exportar, reutilizar y revisión final

Exportar parámetros... exporta un archivo de tarea p4j-task.yml editable a mano. Recoge las opciones ya resueltas, pero nunca el correo ni la contraseña de la cuenta. Después puede restaurar la tarea con Cargar archivo de tarea, en la parte superior de la ventana; esa misma entrada sigue leyendo los p4j-encrypt-run.sh y .bat exportados por versiones anteriores.

En la página de salida, revise al menos:

• el archivo de entrada, el tipo de aplicación, la versión de Java y todas las plataformas de destino;
• el sufijo del archivo, el ajuste del JIT, la capa para escáneres y las opciones de la JVM;
• JavaFX y WebView, el diseño de Spring Boot, o la versión de Tomcat y la ruta de contexto;
• los JAR de dependencia elegidos para proteger y todas las reglas de exclusión;
• el directorio de salida y si se crea un subdirectorio p4jx-xxxx nuevo.

Una vez generado el paquete, use su script de arranque en cada plataforma de destino para comprobar el arranque, el escaneo del framework, la serialización, la reflexión, la carga de recursos y sus flujos de negocio principales. Que las opciones avanzadas estén bien puestas solo significa que la tarea quedó bien configurada; no sustituye a probar el producto terminado.