Configurações do modo avançado do Protector4J

O modo avançado permite definir à mão o alcance da proteção, as opções de compatibilidade e as opções próprias de cada tipo de aplicativo. Na primeira vez que tratar um aplicativo novo, comece pelo modo simples ou faça uma verificação de compatibilidade na página de opções avançadas e ajuste a partir do resultado.

Esta página detalha a seção sobre o modo avançado do Guia da interface gráfica. Para decidir quais classes deixar sem proteção, consulte Compatibilidade e alcance da proteção; para escrever o comando automatizado equivalente, a Referência da linha de comando.

1. Entrar no modo avançado

1. Escolha o tipo de aplicativo e o JAR ou WAR de entrada.
2. Escolha a versão do Java a incluir e pelo menos uma plataforma-alvo.
3. Em Modo, selecione Avançado — personalize você mesmo as opções.
4. Clique em Avançar para abrir a página de opções avançadas.

Se já estiver na página de conferência da saída, clique em Personalizar... para voltar às opções avançadas. Depois das mudanças, volte à página de saída e confirme que o resumo as reflete.

A versão do Java e as plataformas-alvo não podem ser alteradas na página de opções avançadas; para isso, volte à página de entrada. Uma tarefa com várias plataformas gera uma saída independente para cada uma, e as pastas vlxjre delas não são intercambiáveis.

2. Opções comuns

Os quatro tipos de aplicativo compartilham esta seção, embora alguns ajustes valham apenas para certos tipos. A criptografia de bibliotecas não gera scripts de inicialização e, por isso, não tem opções da JVM; o ajuste de sufixo dela serve para sugerir e manter coerente o nome do arquivo de saída.

As opções próprias de cada tipo:

«Sem exclusões» quer dizer que todas as classes de aplicativo daquele tipo são protegidas por padrão. Não quer dizer que as dependências de terceiros também sejam: BOOT-INF/lib no Spring Boot e WEB-INF/lib no Tomcat ficam fora da proteção.

Sufixo do arquivo

Escolher jar muda só o nome; o conteúdo continua sendo P4JX. Ele não abre com ferramentas ZIP ou JAR comuns nem carrega num JRE padrão. Na criptografia de bibliotecas, este ajuste alterna o sufixo do arquivo de saída entre .p4jx e .jar; se você digitar outro sufixo, o nome que informou é mantido.

Opção equivalente:

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

Desativar o JIT para métodos protegidos

Desativar o JIT para métodos protegidos mantém esses métodos longe do compilador JIT, o que reduz a quantidade de código de máquina compilado exposto. Código com muito cálculo pode ficar bem mais lento. O ajuste afeta apenas os métodos protegidos e não coloca toda a JVM em modo interpretado.

Opção equivalente:

--no-jit

Camada ZIP para scanners

A camada expõe apenas recursos públicos, diretórios e os esboços de metadados das classes protegidas — nunca o corpo real dos métodos. Ela existe para que as ferramentas que leem diretamente o diretório central do ZIP continuem funcionando. Não substitui a disposição fat do Spring Boot e não ajuda quando um arquivo é analisado a partir de um fluxo em memória com ZipInputStream ou JarInputStream.

Opção equivalente:

--zip-overlay scanner

Opções de inicialização JVM

Digite uma opção completa por linha, por exemplo:

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

Cada linha é uma opção: nunca coloque duas na mesma. As opções são gravadas nos scripts de inicialização de macOS, Linux e Windows, e no Tomcat também no caminho de inicialização dele. A criptografia de bibliotecas não gera scripts de inicialização, então o campo fica desativado. Exemplos mais completos por plataforma estão em Opções de inicialização JVM.

Na linha de comando, a opção se repete:

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

3. A verificação de compatibilidade e suas recomendações

Nos quatro tipos, Verificação de compatibilidade... examina a entrada atual. Se você aceitar o resultado, a ferramenta incorpora aos seus ajustes as recomendações próprias daquele tipo, principalmente:

• acrescentar classes que deveriam ficar sem proteção;
• ativar a camada ZIP para scanners;
• ajustar o sufixo do arquivo;
• ativar JavaFX e WebView num aplicativo Java ou no Spring Boot;
• escolher a disposição para o Spring Boot;
• escolher Tomcat 9 ou 10.1.

A criptografia de bibliotecas só aplica as recomendações de camada ZIP e de sufixo. Ela foi feita para proteger todas as classes do JAR de entrada e não admite exclusões; assim, se a verificação achar algo que precisa ficar sem proteção — classes JNI ou nativas, por exemplo —, o relatório orienta a mover essas classes para um JAR comum ou a mudar para um modo de empacotamento com proteção seletiva.

Depois de aceitar as recomendações, você pode continuar editando. A verificação preserva as regras de exclusão já existentes e não desliga um JavaFX que você ativou só porque não o detectou. Cancelar a caixa de diálogo não aplica nada.

Os riscos em nível de código apontados no relatório — agentes, JNI, carregadores de classe próprios, bytecode alterado em tempo de execução — em geral não se resolvem mexendo num ajuste. Use Compatibilidade e alcance da proteção para reposicionar as fronteiras do seu código e teste de verdade.

4. Opções do aplicativo Java

Classe principal

Em branco, a Main-Class é lida do manifesto do JAR de entrada. Informe um nome de classe completo apenas se o manifesto não tiver classe principal ou se quiser substituí-la — por exemplo com.example.Main.

Opção equivalente: --main com.example.Main.

Classes a excluir

Por padrão, toda classe do aplicativo é protegida. As classes e pacotes listados aqui ficam sem proteção, o que serve a DTOs, entidades, classes de configuração, classes-ponte JNI e a tudo o que um framework amplie ou que precise ler o próprio bytecode real. A sintaxe está mais abaixo, em «Alcance da proteção e regras de exclusão».

Tempo de execução do JavaFX

Num aplicativo JavaFX simples, marque Incluir o JavaFX no runtime empacotado. Para o WebView há três escolhas:

• Auto (detectar javafx.scene.web): incluído somente se javafx.scene.web for detectado;
• Incluir: sempre inclui fx-webkit;
• Excluir: nunca inclui.

O WebView acrescenta cerca de 40 MB. A interface baixa os componentes correspondentes à sua versão do Java e plataforma-alvo; para indicar uma pasta local do JavaFX, use a linha de comando.

Opções equivalentes: --javafx, --javafx-webview, --no-javafx-webview. Auto não tem opção própria, pois quem decide é o empacotador, a partir das referências do próprio aplicativo.

5. Opções do Spring Boot

Classe principal

Em branco, Start-Class é lida do manifesto. Informe um nome de classe completo para substituí-la.

Opção equivalente: --main com.example.Application.

Disposição

Se a verificação recomendar claramente fat, não force p4jx-fat na esperança de que a camada ZIP compense. Os detalhes de cada disposição estão em Proteger aplicativos Spring Boot.

Opções equivalentes: --layout p4jx-fat, --layout fat, --layout separate.

Proteger os JAR de dependências…

As dependências de BOOT-INF/lib não são protegidas por padrão. Escolha apenas as suas dependências de código fechado; não criptografe pacotes de frameworks de terceiros como Spring, Tomcat, bibliotecas de log ou drivers de banco de dados. Os JAR assinados não podem ser marcados, pois alterá-los quebraria a assinatura.

Ao marcar uma dependência, todas as classes dela ficam protegidas, mas ainda é possível usar Classes a excluir para deixar de fora classes ou pacotes específicos. As três disposições do Spring Boot aceitam a proteção de dependências.

Opção equivalente: --protect-lib 'company-core.jar,company-domain.jar'. A linha de comando aceita também padrões glob; a interface registra os nomes exatos dos JAR marcados.

Classes a excluir e JavaFX

Funcionam como num aplicativo Java. As regras de exclusão valem tanto para as classes do aplicativo quanto para os JAR de dependências marcados para proteção. Um aplicativo de desktop Spring Boot também pode incluir JavaFX e WebView pela aba Tempo de execução do JavaFX.

6. Opções do Tomcat

Versão do Tomcat

• Se o WAR usa javax.servlet.*, escolha Tomcat 9 · javax.
• Se usa jakarta.servlet.*, escolha Tomcat 10.1 · jakarta.

O Tomcat 10.1 exige Java 11 ou posterior. Na dúvida, faça uma verificação de compatibilidade. Se o aplicativo usa javax e jakarta ao mesmo tempo, não force uma versão: resolva antes o conflito de dependências.

O modo avançado não pré-seleciona versão alguma: é preciso aceitar a recomendação da verificação ou escolher uma para seguir adiante. Opções equivalentes: --tomcat-version 9 ou --tomcat-version 10; a linha de comando aceita também auto.

Caminho de contexto

Informe o caminho de implantação começando por /, por exemplo /app. Em branco, usa-se /app. Ao acrescentar um aplicativo a uma pasta de saída do Tomcat já existente, o caminho não pode coincidir com o de outro aplicativo.

Opção equivalente: --context /app.

Classes a excluir

Por padrão, as classes de aplicativo sob WEB-INF/classes são protegidas, e WEB-INF/lib fica de fora. Servlets, filtros, ouvintes, DTOs, classes de configuração, entidades, classes-ponte JNI e tudo o que o contêiner precise ampliar costumam ser excluídos.

7. Alcance da proteção e regras de exclusão

No modo avançado, a interface protege por padrão todas as classes do aplicativo, e você traça a fronteira com o framework usando Classes a excluir. São aceitas três formas de regra:

com.example.SecretService   somente esta classe
com.example.service.*       somente este pacote, sem subpacotes
com.example.service.**      este pacote e todos os subpacotes

Escolha classes na árvore com Escolher... ou digite-as com Adicionar.... Marcar um pacote abrange por padrão os subpacotes; com .* você limita ao pacote em si. No Spring Boot, a árvore mostra também os JAR de dependências marcados para proteção.

O arranjo recomendado é: fronteira pública ou entrada do framework → fachada ou interface comum → implementação central protegida. Não criptografe todas as dependências de terceiros e os pontos de entrada do framework só para a superfície protegida parecer maior.

8. Exportar, reaproveitar e conferir no fim

Exportar parâmetros... exporta um arquivo de tarefa p4j-task.yml editável à mão. Ele registra as opções já resolvidas, mas nunca o e-mail nem a senha da conta. Depois você pode restaurar a tarefa com Carregar arquivo de tarefa, na parte de cima da janela; essa mesma entrada continua lendo os p4j-encrypt-run.sh e .bat exportados por versões anteriores.

Na página de saída, confira pelo menos:

• o arquivo de entrada, o tipo de aplicativo, a versão do Java e todas as plataformas-alvo;
• o sufixo do arquivo, o ajuste do JIT, a camada para scanners e as opções da JVM;
• JavaFX e WebView, a disposição do Spring Boot, ou a versão do Tomcat e o caminho de contexto;
• os JAR de dependências marcados para proteção e todas as regras de exclusão;
• a pasta de saída e se será criada uma subpasta p4jx-xxxx.

Com o pacote pronto, use o script de inicialização dele em cada plataforma-alvo para conferir a inicialização, a varredura do framework, a serialização, a reflexão, o carregamento de recursos e os seus fluxos de negócio principais. Opções avançadas corretas significam apenas que a tarefa foi bem configurada; isso não substitui a conferência do produto final.