Configurações do modo avançado do Protector4J

O modo avançado é usado para determinar manualmente o escopo de proteção, as opções de compatibilidade e parâmetros específicos para cada tipo de aplicação protegida. Ao lidar com um aplicativo novo pela primeira vez, recomenda‑se usar o modo simples ou realizar uma varredura de compatibilidade na página de parâmetros avançados antes de ajustar as configurações com base nos resultados da varredura.

Este texto fornece uma explicação detalhada do modo avançado em Guia de Uso da GUI. Para decidir quais classes devem permanecer desencriptadas, leia também Compatibilidade e escopo de proteção; para criar comandos automatizados, siga as instruções em Referência de parâmetros CLI.

1. Acessar o modo avançado

1. Selecione o tipo de aplicação e insira JAR/WAR.
2. Escolha Versão Java incluída no pacote e pelo menos uma plataforma de destino.
3. Selecione Advanced — customise the options yourself em Mode.
4. Clique em Next para acessar a página de parâmetros avançados.

Se você já estiver na página de confirmação de saída, pode clicar em Customize… para retornar à página de parâmetros avançados. Após fazer as alterações, acesse novamente a página de saída para confirmar que o resumo reflete as novas configurações.

A versão do Java e a plataforma de destino não são alteradas na página de parâmetros avançados; se for necessário ajustá-los, retorne à página de entrada. Tarefas multiplataforma geram saídas independentes para cada plataforma, e os arquivos relacionados a vlxjre não podem ser intercambiados.

2. Opções gerais

Quatro tipos de aplicação compartilham a área de parâmetros avançados, mas algumas configurações têm efeito de acordo com o tipo. O Library Encryption não gera um script de inicialização, portanto não utiliza parâmetros de inicialização do JVM; sua configuração de sufixo de arquivamento é usada para sugerir e sincronizar os nomes dos arquivos de saída.

As configurações específicas para cada tipo de aplicativo são as seguintes:

“Não se exclui a classe” indica que, por padrão, há proteção para todos os tipos de aplicativos desse tipo, mas isso não significa que as dependências de terceiros também sejam protegidas. BOOT-INF/lib do Spring Boot e WEB-INF/lib do Tomcat permanecem em modo normal por padrão.

Sufixo de arquivamento

Ao selecionar jar, apenas o nome do arquivo é alterado; o conteúdo do arquivo continua no formato P4JX, não podendo ser modificado com ferramentas comuns de ZIP/JAR, nem carregado com um JRE comum. Para o Library Encryption, essa configuração altera o sufixo do arquivo de saída para .p4jx/.jar; se o usuário definir outro sufixo personalizado, o nome completo do arquivo será mantido.

CLI correspondente:

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

Proíbe o método de proteção JIT

Ao ativar Disable JIT for protected methods, os métodos protegidos não entram no compilador JIT, o que reduz a superfície de exposição do código máquina após a compilação, mas códigos intensivos em cálculos podem ficar significativamente mais lentos. Essa configuração afeta apenas os métodos protegidos e não altera toda a JVM para um modo puramente interpretativo.

CLI correspondente:

--no-jit

Overlay ZIP do scanner

O overlay expõe apenas metadados de recursos públicos, diretórios e classes de proteção, sem incluir o corpo real dos métodos. Ele é usado para compatibilidade com ferramentas que leem diretamente o diretório central do ZIP, mas não pode substituir o layout do Spring Boot fat, nem resolver cenários de análise de arquivos a partir de fluxos de memória usando ZipInputStream/JarInputStream.

CLI correspondente:

--zip-overlay scanner

Parâmetros de inicialização do JVM

Insira um parâmetro completo em cada linha, por exemplo:

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

Cada linha representa um limite de parâmetro; não insira vários parâmetros na mesma linha. Os parâmetros serão gravados nos scripts de inicialização do macOS/Linux e Windows; os parâmetros do Tomcat também serão incluídos em seu caminho de inicialização. O Library Encryption não gera scripts de inicialização, portanto, a caixa de entrada está indisponível. Exemplos mais completos para diferentes plataformas podem ser encontrados em Configuração de parâmetros de inicialização do JVM.

O CLI correspondente requer o uso repetido de opções:

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

3. Varredura de compatibilidade e recomendações para aplicações

Para os quatro tipos de aplicações, é possível clicar em Compatibility scan… para realizar a varredura dos dados inseridos. Ao aceitar os resultados, a ferramenta combina as recomendações específicas para esse tipo de aplicação nas configurações atuais, incluindo principalmente:

• Adicionar classes que precisam permanecer desencriptadas;
• Ativar o overlay ZIP do scanner;
• Ajustar o sufixo de arquivamento;
• Ativar o JavaFX/WebView para Java Application ou Spring Boot;
• Selecionar o layout para Spring Boot;
• Selecionar 9 ou 10.1 para o Tomcat.

A Library Encryption aplica automaticamente apenas as recomendações de overlay ZIP do scanner e de sufixo de arquivamento. Ela foi projetada para proteger todas as classes no JAR de entrada, sem suporte à exclusão de classes; se a varredura identificar conteúdos que precisam permanecer desencriptados, como classes JNI/nativas, o relatório indicará claramente que eles devem ser movidos para um JAR comum ou que se deve usar um modo de empacotamento de aplicativo que suporte proteção seletiva.

É possível continuar editando após aceitar as recomendações. A varredura manterá as regras de exclusão existentes e não desativará automaticamente o JavaFX habilitado pelo usuário caso o JavaFX não seja detectado. Cancelar a caixa de diálogo significa não aplicar as recomendações.

Os riscos em nível de código presentes nos relatórios de varredura, como Agent, JNI, carregadores de classe personalizados ou reescrita de bytecode em tempo de execução, geralmente não podem ser resolvidos apenas com um interruptor. É necessário ajustar os limites do código conforme Compatibilidade e escopo de proteção e realizar testes práticos.

4. Configurações da Aplicação Java

Main class

Main-Class, que lê o Manifest do JAR de entrada quando deixado vazio. O nome da classe completo deve ser preenchido somente quando o Manifest não contém uma classe principal ou quando é necessário substituir a classe de inicialização padrão, por exemplo, com.example.Main.

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

Classes to exclude

Por padrão, todas as classes da aplicação são protegidas. As classes ou pacotes listados aqui permanecem desencriptados, sendo adequados para DTOs, entidades, classes de configuração, classes de ponte JNI e aquelas que precisam ser aprimoradas pelo framework ou ter seu bytecode real lido. O formato das regras está descrito em “Escopo de proteção e regras de exclusão”.

JavaFX runtime

Para aplicações JavaFX comuns, marque Bundle JavaFX into the packaged runtime. Para WebView, há opções:

• Auto: incluir quando javafx.scene.web for detectado;
• Include: incluir obrigatoriamente fx-webkit;
• Exclude: Deve ser excluído obrigatoriamente.

O WebView aumentará o tamanho em aproximadamente 40 MB. A GUI baixará os recursos de acordo com a versão e plataforma Java alvo; use a CLI quando for necessário especificar um diretório local offline para JavaFX.

CLI correspondentes: --javafx, --javafx-webview e --no-javafx-webview. O Auto não insere opções obrigatórias relacionadas ao WebView, sendo decidido pelo empacotador com base nas referências da aplicação.

5. Configurações do Spring Boot

Main class

Quando deixado em branco, será lido o Start-Class do Manifest. Insira o nome completo da classe quando for necessário substituir a classe de inicialização.

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

Layout

Se a varredura de compatibilidade recomendar explicitamente fat, não force o uso de p4jx-fat após ativar apenas o ZIP overlay. Veja os detalhes da configuração em Proteção de aplicativos Spring Boot.

CLI correspondente: --layout p4jx-fat, --layout fat ou --layout separate.

Protect dependency JARs…

As dependências em BOOT-INF/lib não são protegidas por padrão. Marque apenas as dependências proprietárias de código fechado; evite criptografar pacotes de frameworks de terceiros como Spring, Tomcat, gerenciadores de logs e drivers de banco de dados. JARs assinados serão exibidos como não selecionáveis, pois qualquer alteração pode quebrar sua assinatura.

Ao marcar uma dependência, todas as suas classes serão protegidas, mas as regras de Classes to exclude ainda permitem excluir classes ou pacotes específicos para essa dependência. Todos os três layouts do Spring Boot suportam a proteção de dependências.

CLI correspondente: --protect-lib 'company-core.jar,company-domain.jar'. O CLI também suporta expressões globais; a GUI salva o nome exato do arquivo do JAR selecionado.

Classes to exclude e JavaFX

O modo de uso é o mesmo que o de uma Java Application. As regras de exclusão afetam tanto as classes da aplicação quanto os JARs de dependência selecionados para proteção. Aplicativos desktop Spring Boot + JavaFX também podem ter o JavaFX/WebView empacotado na aba JavaFX runtime.

6. Configurações do Tomcat

Tomcat version

• Use javax.servlet.* para selecionar Tomcat 9 · javax;
• Use jakarta.servlet.* para selecionar Tomcat 10.1 · jakarta.

O Tomcat 10.1 requer pelo menos o Java 11. Se houver dúvidas, execute uma verificação de compatibilidade; se a aplicação usar simultaneamente javax e jakarta, não escolha uma versão à força — corrija primeiro os conflitos de dependência.

O modo avançado não possui versões pré-selecionadas; é necessário aceitar as recomendações da verificação ou fazer uma seleção manual antes de prosseguir. CLI correspondente: --tomcat-version 9 ou --tomcat-version 10; o CLI também permite auto.

Context path

Preencha o caminho de deploy que começa com /, como /app. Se deixado em branco, será usado /app. Ao adicionar uma aplicação ao diretório de saída existente do Tomcat, o context path não pode coincidir com o de aplicativos já existentes.

CLI correspondente: --context /app.

Classes to exclude

A proteção padrão aplica-se às classes do WEB-INF/classes, enquanto o WEB-INF/lib, por ser dependente, não é protegido por padrão. Geralmente, classes como Servlet, Filter, Listener, DTO, configurações, entidades, classes de ponte JNI e classes que precisam de aprimoramentos no contêiner devem ser excluídas.

7. Escopo de proteção e regras de exclusão

O modo avançado da GUI oferece proteção padrão para todos os tipos de aplicativo, reservando as bordas da estrutura por meio de Classes to exclude. São suportadas três regras:

com.example.SecretService   Apenas corresponde a esta classe
com.example.service.*       Corresponde ao pacote atual, sem subpacotes
com.example.service.**      Corresponde ao pacote atual e a todos os subpacotes

É possível selecionar a partir da árvore de classes usando Choose…, ou adicionar itens manualmente por meio de Add…. A seleção de pacotes cobre, por padrão, o pacote atual e seus subpacotes; use .* quando for necessário excluir apenas o pacote atual. A árvore de classes do Spring Boot também exibe os JARs de dependência que foram selecionados para proteção.

A estrutura recomendada é “Entrada de fronteira/padrão → Facade ou interface comum → Implementação central protegida”. Não criptografe todas as dependências de terceiros ou pontos de entrada de frameworks apenas para ampliar o escopo de proteção.

8. Exportação, reutilização e revisão final

Clicando em Export parameters…, é possível exportar:

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

O script de exportação salva as opções atualmente analisadas, mas não grava o e-mail ou senha da conta. Posteriormente, a tarefa pode ser restaurada por meio de Load Task File, localizado na parte superior.

Após acessar a página de saída, verifique pelo menos os seguintes itens:

• Insira o arquivo, o tipo de aplicativo, a versão do Java e todas as plataformas de destino;
• Sufixo de arquivamento, JIT, overlay do scanner e parâmetros da JVM;
• JavaFX/WebView, layout do Spring Boot ou versão/contexto do Tomcat;
• JARs de dependência protegidos e todas as regras de exclusão;
• Diretório de saída e se um novo subdiretório p4jx-xxxx deve ser criado.

Após a geração, é necessário utilizar scripts de inicialização dentro do pacote em cada plataforma-alvo para verificar a inicialização, a varredura do framework, a serialização, o reflexo, o carregamento de recursos e os caminhos de negócio principais. A configuração correta da página de parâmetros avançados apenas indica que os parâmetros da tarefa foram definidos, mas não substitui a verificação do produto final.