Protector4J 고급 모드 설정
고급 모드는 보호 범위, 호환성 옵션, 그리고 애플리케이션 유형에 특화된 매개변수를 수동으로 결정하는 데 사용됩니다. 새로운 애플리케이션을 처음 처리할 때는 먼저 일반 모드를 사용하거나 고급 설정 페이지에서 호환성 검사를 한 번 수행한 후, 검사 결과에 따라 설정을 조정하는 것이 권장됩니다.
이 문서는 GUI 사용 가이드의 고급 모드에 대한 상세 설명입니다. 어떤 클래스들을 암호화하지 않은 상태로 유지해야 하는지 판단해야 할 경우 호환성 검사와 보호 범위와 함께 읽어보시기 바랍니다. 자동화된 명령어를 작성해야 할 경우에는 CLI 매개변수 참고를 참고하십시오.
1. 고급 모드로 진입
- 애플리케이션 유형을 선택하고 JAR/WAR를 입력합니다.
- 포함된 Java 버전와 하나 이상의 대상 플랫폼을 선택합니다.
- Mode 내에서 Advanced — customise the options yourself를 선택합니다.
- Next를 클릭하여 고급 설정 페이지로 진입합니다.
이미 출력 확인 페이지에 있는 경우, **Customize…**를 클릭하여 고급 파라미터 페이지로 돌아갈 수 있습니다. 수정을 마친 후 다시 출력 페이지로 가서 요약 정보에 새로운 설정이 반영되었는지 확인하세요.
Java 버전과 대상 플랫폼은 고급 파라미터 페이지에서 수정할 수 없습니다. 조정이 필요한 경우 입력 페이지로 돌아가야 합니다. 다중 플랫폼 작업의 경우 각 플랫폼마다 별도의 출력 결과가 생성되며, 여기서 vlxjre는 서로 교체할 수 없습니다.
2. 일반 옵션
네 가지 애플리케이션 유형은 모두 고급 파라미터 영역을 공유하지만, 일부 설정은 유형에 따라 적용됩니다. Library Encryption의 경우 시작 스크립트가 생성되지 않으므로 JVM 시작 파라미터가 사용되지 않습니다. 또한 아카이브 파일의 확장자 설정은 출력 파일명을 제안하고 동기화하는 데 사용됩니다.
| GUI 설정 | 기본값 | 역할 | 권장 사항 |
|---|---|---|---|
| Archive suffix | p4jx | 애플리케이션 아카이브의 이름을 .p4jx 또는 .jar로 지정합니다. | .p4jx 그대로 유지하며, 서드파티 컴포넌트가 .jar라는 파일명을 하드코딩한 경우에만 jar로 변경합니다. |
| Disable JIT for protected methods | 끄기 | 보호 방법이 인터프리터 내에서만 실행되도록 합니다. | 보안상 민감하고 성능 테스트가 완료된 경우에만 활성화됩니다. |
| Append scanner ZIP overlay | 끄기 | ZIP 구조 스캐너가 읽을 수 있는 호환성 뷰를 추가합니다. | 호환성 스캔 권장 사항이 있거나 애플리케이션이 실제로 물리적 ZIP 구조를 읽을 때에만 활성화됩니다. |
| JVM startup options | 빈 값 | 생성된 시작 스크립트에 JVM 매개변수를 작성합니다. | 각 줄에 하나의 완전한 매개변수를 입력합니다. |
| Compatibility scan… | 자동으로 실행되지 않습니다. | 입력 내용을 스캔하여 신중한 권장 사항을 제공합니다. | 새로운 애플리케이션, 프레임워크 업그레이드 또는 보호 범위가 변경된 후 다시 실행합니다. |
각 애플리케이션 유형에 실제로 적용되는 전용 설정은 다음과 같습니다:
| 애플리케이션 유형 | 전용 설정 | 초기 상태 | CLI 대응 항목 |
|---|---|---|---|
| Java Application | Main class, Classes to exclude, JavaFX/WebView | 주 클래스는 Manifest에서 가져오며, 기본적으로 클래스는 제외되지 않고 JavaFX도 패키징되지 않음 | --main, --exclude, --javafx, --javafx-webview / --no-javafx-webview |
| Spring Boot | Main class, Layout, Protect dependency JARs, Classes to exclude, JavaFX/WebView | 주 클래스는 Start-Class; p4jx-fat에서 가져오며, 종속성은 보호되지 않고 클래스는 제외되지 않으며 JavaFX도 패키징되지 않음 | --main, --layout, --protect-lib, --exclude, JavaFX 관련 옵션 |
| Tomcat | Tomcat version, Context path, Classes to exclude | 버전이 선택되지 않았으며, /app가 적용되고 클래스는 제외되지 않음 | --tomcat-version, --context, --exclude |
“클래스를 배제하지 않음”는 기본적으로 해당 애플리케이션 유형의 모든 애플리케이션 클래스를 보호하지만, 서드파티 의존성까지 함께 보호하는 것은 아닙니다. Spring Boot의 BOOT-INF/lib와 Tomcat의 WEB-INF/lib는 기본적으로 일반 상태를 유지합니다.
아카이브 접미사
jar를 선택하면 파일명만 변경되며, 파일 내용은 여전히 P4JX 형식을 유지합니다. 따라서 일반 ZIP/JAR 도구로는 수정할 수 없으며, 일반 JRE로도 로드할 수 없습니다. Library Encryption의 경우, 이 설정을 통해 선택된 출력 파일의 .p4jx/.jar 접미사가 변경됩니다. 사용자가 다른 사용자 정의 접미사를 지정한 경우에는 원래의 파일명이 그대로 유지됩니다.
해당 CLI:
--archive-suffix p4jx
--archive-suffix jar
보호 방식인 JIT 금지
Disable JIT for protected methods를 활성화하면 보호된 메서드가 JIT 컴파일러를 거치지 않아, 컴파일된 기계어가 노출될 가능성을 줄일 수 있습니다. 하지만 연산 집약적인 코드의 경우 성능이 현저히 저하될 수 있습니다. 이 설정은 보호된 메서드에만 영향을 미치며, 전체 JVM을 순수 해석 모드로 전환하지는 않습니다.
해당 CLI:
--no-jit
스캐너 ZIP overlay
overlay는 공개된 리소스, 디렉토리, 그리고 보호 관련 메타데이터만 노출하며 실제 메서드 본문은 포함하지 않습니다. 이는 ZIP의 중앙 디렉토리를 직접 읽는 도구와의 호환성을 위해 사용되지만, Spring Boot fat 레이아웃을 대체할 수 없으며, 메모리 스트림에서 ZipInputStream/JarInputStream를 사용해 아카이브를 파싱하는 상황도 해결해 주지 못합니다.
해당 CLI:
--zip-overlay scanner
JVM 시작 파라미터
각 줄에 하나의 완전한 파라미터를 입력합니다. 예:
-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8
각 줄이 하나의 파라미터 경계이므로 여러 파라미터를 같은 줄에 적으면 안 됩니다. 파라미터는 macOS/Linux 및 Windows 시작 스크립트에 기록되며, Tomcat 파라미터도 해당 시작 경로에 포함됩니다. Library Encryption의 경우 시작 스크립트가 생성되지 않으므로 입력란이 사용되지 않습니다. 보다 완전한 플랫폼 예시는 JVM 시작 파라미터 설정를 참조하십시오.
해당 CLI에서는 옵션을 반복해서 사용해야 합니다:
--jvm-option -Xms512m --jvm-option -Xmx2g
3. 호환성 스캔 및 애플리케이션 권장 사항
네 가지 애플리케이션 유형 모두 **Compatibility scan…**를 클릭하여 현재 입력 내용을 스캔할 수 있습니다. 결과를 수락하면 도구는 해당 애플리케이션 유형에 적용 가능한 권장 사항들을 현재 설정에 통합해 주며, 주요 내용은 다음과 같습니다:
- 암호화되지 않은 상태로 유지해야 하는 클래스를 추가합니다;
- 스캐너 ZIP overlay를 활성화합니다;
- 아카이브 접미사를 조정합니다;
- Java Application 또는 Spring Boot에 JavaFX/WebView를 활성화합니다;
- Spring Boot에 사용할 레이아웃을 선택합니다;
- Tomcat에 9 또는 10.1을 선택합니다.
Library Encryption은 스캐너 ZIP overlay 및 아카이브 접미사 관련 권장 사항만 자동으로 적용합니다. 이 기능은 설계상 입력된 JAR 내의 모든 클래스를 보호하도록 되어 있어 클래스 제외 기능을 지원하지 않습니다. 스캔 과정에서 JNI/네이티브 클래스와 같이 암호화되지 않은 상태로 유지해야 하는 내용이 발견될 경우, 보고서에 이러한 요소들을 일반 JAR로 분리하거나 선택적 보호를 지원하는 애플리케이션 패키징 모드를 사용하라는 명확한 안내가 표시됩니다.
권장 사항을 수락한 후에도 계속해서 편집할 수 있습니다. 스캔은 기존의 제외 규칙들을 그대로 유지하며, JavaFX가 감지되지 않았다고 해서 사용자가 활성화한 JavaFX를 자동으로 비활성화하지 않습니다. 대화상자를 취소하면 권장 사항들은 적용되지 않습니다.
스캔 보고서에 나타나는 Agent, JNI, 사용자 정의 클래스 로더 또는 런타임 바이트코드 수정과 같은 코드 수준의 위험은 일반적으로 단순한 스위치 조정만으로는 해결할 수 없습니다. 호환성 검사와 보호 범위를 사용하여 코드 경계를 조정한 후 실제 테스트를 진행해야 합니다.
4. Java Application 설정
Main class
빈 값으로 남겨두면 입력된 JAR Manifest의 Main-Class 내용이 읽어집니다. Manifest에 메인 클래스가 없거나 기본 시작 클래스를 대체해야 하는 경우에만 com.example.Main와 같은 완전한 클래스명을 입력해야 합니다.
해당 CLI: --main com.example.Main.
Classes to exclude
애플리케이션 클래스는 기본적으로 모두 보호됩니다. 이 목록에 포함된 클래스나 패키지는 암호화되지 않은 상태로 유지되며, DTO, 엔티티, 설정 클래스, JNI 브리지 클래스, 그리고 프레임워크에 의해 강화되거나 실제 바이트코드가 읽히는 것이 필요한 클래스에 적합합니다. 규칙 형식은 “보호 범위와 제외 규칙”를 참조하십시오.
JavaFX runtime
일반 JavaFX 애플리케이션의 경우 Bundle JavaFX into the packaged runtime를 선택합니다. WebView의 경우 다음 중 선택 가능합니다:
- Auto:
javafx.scene.web가 감지될 때 포함됨; - Include:
fx-webkit를 반드시 포함함; - Exclude:강제로 포함하지 않음.
WebView는 약 40 MB가 추가로 필요합니다. GUI는 대상 Java 버전 및 플랫폼에 맞는 자료를 다운로드하며, 로컬 오프라인 JavaFX 디렉토리를 지정해야 하는 경우 CLI를 사용합니다.
해당 CLI: --javafx, --javafx-webview, --no-javafx-webview. Auto는 별도의 WebView 강제 옵션을 작성하지 않으며, 패키징 도구가 애플리케이션의 참조에 따라 결정합니다.
5. Spring Boot 설정
Main class
빈 값으로 두면 Manifest의 Start-Class가 읽힙니다. 시작 클래스를 재정의해야 하는 경우 전체 클래스명을 입력해야 합니다.
해당 CLI: --main com.example.Application.
Layout
| 레이아웃 | 적용 시나리오 |
|---|---|
p4jx-fat | 기본값; 일반적인 Spring Boot 서비스로, 보호 범위가 가장 넓음 |
fat | ClassGraph, Reflections 등은 실제 Spring Boot JAR 구조가 필요함 |
separate | 평면형 lib/* 클래스 경로를 사용하는 구버전 통합 환경을 반드시 사용해야 함 |
호환성 검사에서 명시적으로 fat를 권장하는 경우, ZIP overlay만 활성화한 상태에서 계속 p4jx-fat를 강제로 사용하지 마십시오. 세부 구성은 Spring Boot 애플리케이션을 보호를 참조하십시오.
해당 CLI: --layout p4jx-fat, --layout fat 또는 --layout separate.
Protect dependency JARs…
BOOT-INF/lib에 포함된 종속성들은 기본적으로 보호되지 않습니다. 자체적인 오픈소스가 아닌 종속성만 선택하고, Spring, Tomcat, 로깅, 데이터베이스 드라이버와 같은 서드파티 프레임워크 패키지는 암호화하지 마십시오. 서명이 포함된 JAR의 경우 내용을 수정하면 서명이 깨지므로 선택할 수 없는 상태로 표시됩니다.
하나의 종속성을 선택하면 그 안에 있는 모든 클래스가 보호되지만, Classes to exclude 규칙을 통해 해당 종속성 내의 특정 클래스나 패키지는 제외시킬 수 있습니다. 세 가지 Spring Boot 구성 모두에서 종속성 보호 기능을 지원합니다.
해당 CLI: --protect-lib 'company-core.jar,company-domain.jar'. CLI도 glob 기능을 지원하며, GUI에서는 선택된 JAR의 정확한 파일명이 저장됩니다.
JavaFX와 관련하여 제외할 클래스들
사용 방법은 Java Application과 동일합니다. 제외 규칙은 애플리케이션 클래스와 보호가 지정된 의존성 JAR 모두에 적용됩니다. Spring Boot + JavaFX 데스크톱 애플리케이션의 경우에도 JavaFX runtime 탭에서 JavaFX/WebView를 패키징할 수 있습니다.
6. Tomcat 설정
Tomcat version
javax.servlet.*를 사용하는 WAR의 경우 Tomcat 9 · javax를 선택합니다.jakarta.servlet.*를 사용하는 WAR의 경우 Tomcat 10.1 · jakarta를 선택합니다.
Tomcat 10.1의 경우 최소 Java 11이 필요합니다. 확실하지 않을 때는 호환성 검사를 실행하십시오. 애플리케이션이 javax와 jakarta를 혼용하는 경우, 강제로 버전을 선택하지 말고 먼저 의존성 충돌을 해결해야 합니다.
고급 모드에는 사전 지정된 버전이 없으므로, 스캔 결과를 수락하거나 수동으로 선택한 후에 다음 단계로 진행해야 합니다. 해당 CLI는 --tomcat-version 9 또는 --tomcat-version 10이며, CLI에서는 auto도 사용할 수 있습니다.
Context path
/로 시작하는 배포 경로를 입력하십시오. 예: /app. 빈 칸으로 남겨두면 /app가 사용됩니다. 기존 Tomcat의 출력 디렉터리에 애플리케이션을 추가할 때는 context path가 기존 애플리케이션과 중복되어서는 안 됩니다.
해당 CLI: --context /app.
Classes to exclude
기본적으로 WEB-INF/classes에 속한 애플리케이션 클래스들이 보호되며, WEB-INF/lib는 기본적으로 보호되지 않습니다. 일반적으로 Servlet, Filter, Listener, DTO, 설정 파일, 엔티티, JNI 브리지 클래스 및 컨테이너에서 향상이 필요한 클래스들은 제외해야 합니다.
7. 보호 범위 및 제외 규칙
고급 모드의 GUI는 기본적으로 모든 애플리케이션 클래스를 보호하며, Classes to exclude를 통해 프레임워크 경계를 지정합니다. 세 가지 규칙을 지원합니다:
com.example.SecretService 이 클래스만 일치시킵니다.
com.example.service.* 현재 패키지를 일치시키며, 하위 패키지는 포함하지 않습니다.
com.example.service.** 현재 패키지와 모든 하위 패키지를 일치시킵니다.
**Choose…**를 사용하여 클래스 트리에서 선택할 수도 있고, **Add…**를 통해 수동으로 추가할 수도 있습니다. 패키지 선택 시 기본적으로 현재 패키지와 하위 패키지가 포함되며, 현재 패키지만 제외하고자 할 경우 .*를 사용합니다. Spring Boot 클래스 트리에는 선택된 보호 대상의 의존성 JAR도 함께 표시됩니다.
권장되는 구조는 “공개 경계/프레임워크 입구 → 일반 패사드 또는 인터페이스 → 보호된 핵심 구현”입니다. 보호 범위를 확대하기 위해 모든 서드파티 의존성이나 프레임워크 엔트리를 암호화해서는 안 됩니다.
8. 내보내기, 재사용 및 최종 검토
**Export parameters…**를 클릭하면 다음 내용을 내보낼 수 있습니다:
p4j-encrypt-run.shp4j-encrypt-run.bat
내보내기 스크립트는 현재 해석된 옵션들을 저장하지만, 계정 이메일과 비밀번호는 포함하지 않습니다. 이후 상단의 Load Task File를 통해 작업을 복원할 수 있습니다.
결과 페이지로 이동한 후에는 다음 항목들을 반드시 검토해야 합니다:
- 파일, 애플리케이션 유형, Java 버전 및 모든 대상 플랫폼을 입력합니다.
- 아카이빙 접미사, JIT, scanner overlay 및 JVM 매개변수;
- JavaFX/WebView, Spring Boot 레이아웃 또는 Tomcat 버전/context;
- 보호되는 종속성 JAR 및 모든 제외 규칙;
- 출력 디렉토리와 새로운
p4jx-xxxx하위 디렉토리를 생성할지 여부.
생성된 후에는 각 목표 플랫폼에서 패키지 내 시작 스크립트를 사용하여 시작 과정, 프레임워크 스캔, 직렬화, 반사, 리소스 로딩 및 핵심 비즈니스 경로를 검증해야 합니다. 고급 매개변수 페이지의 설정이 올바르다고 해서 작업 매개변수가 모두 설정되었다는 의미이며, 최종 결과물에 대한 검증을 대체할 수는 없습니다.