Protector4J 고급 모드 설정
고급 모드에서는 보호 범위, 호환성 옵션, 애플리케이션 유형별 전용 옵션을 직접 설정할 수 있습니다. 새 애플리케이션을 처음 다룰 때는 먼저 간단 모드를 쓰거나, 고급 옵션 페이지에서 호환성 검사를 한 번 실행하고 그 결과에 따라 조정하는 것이 좋습니다.
이 문서는 GUI 가이드의 고급 모드 부분을 자세히 설명한 것입니다. 어떤 클래스를 보호하지 않은 상태로 둘지 판단할 때는 호환성과 보호 범위를, 같은 내용을 자동화 명령으로 쓸 때는 CLI 레퍼런스를 참고하세요.
1. 고급 모드로 들어가기
- 애플리케이션 유형을 고르고 입력할 JAR 또는 WAR를 지정합니다.
- 함께 넣을 Java 버전과 대상 플랫폼을 하나 이상 선택합니다.
- 모드에서 고급 — 옵션을 직접 설정합니다를 선택합니다.
- 다음을 클릭해 고급 옵션 페이지를 엽니다.
이미 출력 확인 페이지에 있다면 사용자 정의 ... 를 클릭해 고급 옵션으로 돌아갈 수 있습니다. 수정한 뒤 출력 페이지로 돌아가 요약에 반영되었는지 확인하세요.
Java 버전과 대상 플랫폼은 고급 옵션 페이지에서 바꿀 수 없습니다. 바꾸려면 입력 페이지로 돌아가세요. 여러 플랫폼을 지정한 작업은 플랫폼별로 독립된 출력을 만들며, 각각의 vlxjre는 서로 바꿔 쓸 수 없습니다.
2. 일반 옵션
네 가지 애플리케이션 유형이 이 영역을 공유하지만, 일부 설정은 특정 유형에만 적용됩니다. 라이브러리 암호화는 실행 스크립트를 만들지 않으므로 JVM 시작 옵션이 없습니다. 아카이브 확장자 설정은 출력 파일 이름의 권장과 동기화에 쓰입니다.
| 설정 | 기본값 | 역할 | 권장 |
|---|---|---|---|
| 아카이브 확장자 | p4jx | 애플리케이션 아카이브를 .p4jx 또는 .jar 이름으로 만듭니다 | .p4jx를 유지하세요. 서드파티 구성 요소가 .jar 파일 이름을 하드코딩한 경우에만 jar로 바꿉니다. |
| 보호된 메서드에 대해 JIT 비활성화 | 꺼짐 | 보호 대상 메서드를 인터프리터로만 실행합니다 | 코드 민감도가 높고 성능 영향을 확인한 경우에 켜세요. |
| 스캐너 ZIP 오버레이 추가 | 꺼짐 | ZIP 구조를 검사하는 도구를 위한 호환 뷰를 더합니다 | 호환성 검사가 권장하거나, 애플리케이션이 실제로 물리 ZIP 구조를 읽는 경우에만 켜세요. |
| JVM 시작 옵션 | 비어 있음 | 생성되는 실행 스크립트에 JVM 옵션을 기록합니다 | 한 줄에 하나씩 완전한 형태로 입력하세요. |
| 호환성 검사 ... | 자동 실행 안 함 | 입력을 검사하고 보수적인 권장을 제시합니다 | 새 애플리케이션, 프레임워크 업데이트 후, 보호 범위 변경 후에 다시 실행하세요. |
애플리케이션 유형별 전용 옵션은 다음과 같습니다.
| 유형 | 전용 옵션 | 초기 상태 | 대응하는 CLI 옵션 |
|---|---|---|---|
| Java 애플리케이션 | 메인 클래스, 제외할 클래스, JavaFX와 WebView | 메인 클래스는 매니페스트에서 가져옴. 제외 없음. JavaFX 미포함 | --main, --exclude, --javafx, --javafx-webview / --no-javafx-webview |
| Spring Boot | 메인 클래스, 레이아웃, 의존성 JAR 보호, 제외할 클래스, JavaFX와 WebView | 메인 클래스는 Start-Class에서 가져옴. 레이아웃은 p4jx-fat. 의존성 보호 안 함. 제외 없음. JavaFX 미포함 | --main, --layout, --protect-lib, --exclude 및 JavaFX 관련 옵션 |
| Tomcat | Tomcat 버전, 컨텍스트 경로, 제외할 클래스 | 버전 미선택. 컨텍스트 경로는 /app. 제외 없음 | --tomcat-version, --context, --exclude |
「제외 없음」은 해당 유형의 애플리케이션 클래스를 모두 보호한다는 뜻이며, 서드파티 의존성까지 보호한다는 뜻은 아닙니다. Spring Boot의 BOOT-INF/lib와 Tomcat의 WEB-INF/lib는 기본적으로 보호 범위 밖입니다.
아카이브 확장자
jar를 골라도 파일 이름만 바뀔 뿐 내용은 여전히 P4JX입니다. 일반 ZIP이나 JAR 도구로는 열 수 없고 표준 JRE로도 읽을 수 없습니다. 라이브러리 암호화에서는 이 설정이 출력 파일 확장자를 .p4jx와 .jar 사이에서 바꿉니다. 다른 확장자를 직접 입력하면 입력한 파일 이름이 그대로 유지됩니다.
대응하는 CLI 옵션:
--archive-suffix p4jx
--archive-suffix jar
보호된 메서드에 대해 JIT 비활성화
보호된 메서드에 대해 JIT 비활성화를 켜면 보호 대상 메서드가 JIT 컴파일러로 넘어가지 않아, 컴파일된 기계어가 드러나는 범위를 줄일 수 있습니다. 연산이 많은 코드는 눈에 띄게 느려질 수 있습니다. 이 설정은 보호 대상 메서드에만 영향을 주며, JVM 전체를 인터프리터 실행으로 바꾸지는 않습니다.
대응하는 CLI 옵션:
--no-jit
스캐너 ZIP 오버레이
오버레이가 드러내는 것은 공개 리소스, 디렉터리, 보호 대상 클래스의 메타데이터 스텁뿐이며 실제 메서드 본문은 결코 포함되지 않습니다. ZIP 중앙 디렉터리를 직접 읽는 도구가 계속 동작하게 하려는 것입니다. Spring Boot의 fat 레이아웃을 대신하지 못하고, ZipInputStream이나 JarInputStream으로 메모리 스트림에서 아카이브를 해석하는 경우에도 도움이 되지 않습니다.
대응하는 CLI 옵션:
--zip-overlay scanner
JVM 시작 옵션
한 줄에 하나씩 완전한 형태로 입력합니다. 예:
-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8
한 줄이 하나의 옵션입니다. 두 개를 같은 줄에 쓰지 마세요. 이 옵션들은 macOS, Linux, Windows의 실행 스크립트에 기록되고, Tomcat의 경우 그 시작 경로에도 기록됩니다. 라이브러리 암호화는 실행 스크립트를 만들지 않으므로 이 입력란을 쓸 수 없습니다. 플랫폼별 자세한 예제는 JVM 시작 옵션을 참고하세요.
대응하는 CLI에서는 옵션을 반복합니다.
--jvm-option -Xms512m --jvm-option -Xmx2g
3. 호환성 검사와 그 권장 사항
네 가지 유형 모두 호환성 검사 ... 로 현재 입력을 검사할 수 있습니다. 결과를 받아들이면 해당 유형에 맞는 권장 사항이 현재 설정에 병합됩니다. 주요 내용은 다음과 같습니다.
- 보호하지 않은 상태로 두어야 할 클래스 추가
- 스캐너 ZIP 오버레이 사용
- 아카이브 확장자 조정
- Java 애플리케이션이나 Spring Boot에서 JavaFX와 WebView 사용
- Spring Boot의 레이아웃 선택
- Tomcat 9 또는 10.1 선택
라이브러리 암호화에서 자동으로 적용되는 것은 스캐너 ZIP 오버레이와 아카이브 확장자 두 가지뿐입니다. 입력 JAR 안의 모든 클래스를 보호하도록 설계되어 제외를 지원하지 않으므로, 보호하지 않아야 할 것(JNI나 네이티브 클래스 등)이 발견되면 그 클래스를 일반 JAR로 옮기거나 선택적 보호를 지원하는 패키징 모드로 바꾸라고 보고서가 안내합니다.
권장 사항을 받아들인 뒤에도 계속 편집할 수 있습니다. 검사는 기존 제외 규칙을 유지하며, JavaFX가 감지되지 않았다는 이유로 직접 켠 JavaFX를 끄지도 않습니다. 대화 상자를 취소하면 아무것도 적용되지 않습니다.
보고서에 나오는 코드 수준의 위험(에이전트, JNI, 사용자 정의 클래스 로더, 실행 중 바이트코드 변경)은 보통 설정만 바꿔서는 해결되지 않습니다. 호환성과 보호 범위를 참고해 코드 경계를 조정하고 실제로 시험해 보세요.
4. Java 애플리케이션 옵션
메인 클래스
비워 두면 입력 JAR의 매니페스트에서 Main-Class를 읽습니다. 매니페스트에 메인 클래스가 없거나 이를 덮어쓰려는 경우에만 전체 클래스 이름을 입력합니다 (예: com.example.Main).
대응하는 CLI 옵션: --main com.example.Main.
제외할 클래스
기본적으로 모든 애플리케이션 클래스를 보호합니다. 여기에 적은 클래스와 패키지는 보호되지 않은 상태로 남습니다. DTO, 엔티티, 설정 클래스, JNI 브리지 클래스, 프레임워크가 확장하는 클래스, 자기 자신의 실제 바이트코드를 읽어야 하는 클래스에 적합합니다. 규칙 표기는 아래 「보호 범위와 제외 규칙」을 참고하세요.
JavaFX 런타임
일반 JavaFX 애플리케이션은 JavaFX를 패키지 런타임에 포함을 선택하세요. WebView는 세 가지 방식 중에서 고를 수 있습니다.
- 자동 (javafx.scene.web 탐지):
javafx.scene.web이 감지된 경우에만 포함합니다. - 포함: 항상
fx-webkit을 포함합니다. - 제외: 포함하지 않습니다.
WebView는 약 40 MB가 늘어납니다. GUI는 대상 Java 버전과 플랫폼에 맞는 구성 요소를 내려받습니다. 로컬 오프라인 JavaFX 디렉터리를 지정하려면 CLI를 쓰세요.
대응하는 CLI 옵션: --javafx, --javafx-webview, --no-javafx-webview. 자동에는 추가 옵션이 없습니다. 패키저가 애플리케이션 자체의 참조를 보고 판단하기 때문입니다.
5. Spring Boot 옵션
메인 클래스
비워 두면 매니페스트에서 Start-Class를 읽습니다. 덮어쓰려면 전체 클래스 이름을 입력합니다.
대응하는 CLI 옵션: --main com.example.Application.
레이아웃
| 레이아웃 | 적합한 상황 |
|---|---|
p4jx-fat | 기본 레이아웃. 표준적인 Spring Boot 서비스이며 보호 범위가 가장 넓습니다. |
fat | ClassGraph나 Reflections를 쓰는 등 물리적인 Spring Boot JAR 구조가 필요한 경우. |
separate | lib/* 평면 클래스패스를 요구하는 오래된 연동 환경. |
호환성 검사가 fat을 분명히 권장한다면 p4jx-fat으로 되돌리고 ZIP 오버레이로 메우려 하지 마세요. 각 레이아웃의 자세한 내용은 Spring Boot 애플리케이션 보호를 참고하세요.
대응하는 CLI 옵션: --layout p4jx-fat, --layout fat, --layout separate.
의존성 JAR 보호
BOOT-INF/lib의 의존성은 기본적으로 보호되지 않습니다. 자사의 비공개 의존성만 선택하고, Spring, Tomcat, 로깅 라이브러리, 데이터베이스 드라이버 같은 서드파티 프레임워크는 암호화하지 마세요. 서명된 JAR는 수정하면 서명이 깨지므로 선택할 수 없습니다.
의존성을 선택하면 그 안의 모든 클래스가 보호되지만, 제외할 클래스를 써서 특정 클래스나 패키지를 보호 대상에서 뺄 수 있습니다. 세 가지 Spring Boot 레이아웃 모두 의존성 보호를 지원합니다.
대응하는 CLI 옵션: --protect-lib 'company-core.jar,company-domain.jar'. CLI에서는 glob도 쓸 수 있고, GUI는 선택한 JAR의 정확한 파일 이름을 기록합니다.
제외할 클래스와 JavaFX
사용법은 Java 애플리케이션과 같습니다. 제외 규칙은 애플리케이션 클래스와, 보호 대상으로 선택한 의존성 JAR 양쪽에 적용됩니다. Spring Boot 데스크톱 애플리케이션도 JavaFX 런타임 탭에서 JavaFX와 WebView를 포함할 수 있습니다.
6. Tomcat 옵션
Tomcat 버전
- WAR가
javax.servlet.*을 쓰면 Tomcat 9 · javax를 선택합니다. jakarta.servlet.*을 쓰면 Tomcat 10.1 · jakarta를 선택합니다.
Tomcat 10.1에는 Java 11 이상이 필요합니다. 판단하기 어려우면 호환성 검사를 실행하세요. javax와 jakarta를 함께 쓰고 있다면 버전을 억지로 고르지 말고 의존성 충돌부터 해결하세요.
고급 모드는 버전을 미리 선택해 두지 않습니다. 검사 권장을 받아들이거나 직접 고르기 전에는 다음 단계로 넘어갈 수 없습니다. 대응하는 CLI 옵션은 --tomcat-version 9 또는 --tomcat-version 10이며, CLI에서는 auto도 쓸 수 있습니다.
컨텍스트 경로
/로 시작하는 배포 경로를 입력합니다 (예: /app). 비워 두면 /app이 쓰입니다. 기존 Tomcat 출력 디렉터리에 애플리케이션을 추가할 때는 컨텍스트 경로가 기존 것과 겹치면 안 됩니다.
대응하는 CLI 옵션: --context /app.
제외할 클래스
기본적으로 WEB-INF/classes 아래의 애플리케이션 클래스를 보호하고 WEB-INF/lib는 보호 범위 밖입니다. 서블릿, 필터, 리스너, DTO, 설정 클래스, 엔티티, JNI 브리지 클래스, 컨테이너가 확장해야 하는 클래스는 보통 제외해야 합니다.
7. 보호 범위와 제외 규칙
고급 모드에서 GUI는 기본적으로 모든 애플리케이션 클래스를 보호하고, 제외할 클래스로 프레임워크와의 경계를 그립니다. 규칙은 세 가지 형태를 지원합니다.
com.example.SecretService 이 클래스만
com.example.service.* 이 패키지만 (하위 패키지 제외)
com.example.service.** 이 패키지와 모든 하위 패키지
선택 ... 으로 클래스 트리에서 고르거나 추가 ... 로 직접 입력할 수 있습니다. 패키지를 고르면 기본적으로 하위 패키지까지 포함되며, .* 를 쓰면 그 패키지 자체로만 한정됩니다. Spring Boot의 클래스 트리에는 보호 대상으로 선택한 의존성 JAR도 표시됩니다.
권장하는 구성은 공개 경계 또는 프레임워크 진입점 → 일반 파사드나 인터페이스 → 보호된 핵심 구현 순서입니다. 보호 범위를 넓어 보이게 하려고 서드파티 의존성과 프레임워크 진입점까지 암호화하지 마세요.
8. 내보내기, 재사용, 최종 확인
매개변수 내보내기 ... 를 클릭하면 직접 편집할 수 있는 p4j-task.yml 작업 파일을 내보낼 수 있습니다. 확정된 옵션이 기록되지만 계정 이메일과 비밀번호는 절대 기록되지 않습니다. 나중에 창 위쪽의 작업 파일 불러오기로 작업을 복원할 수 있으며, 이 입구는 이전 버전이 내보낸 p4j-encrypt-run.sh와 .bat도 계속 읽을 수 있습니다.
출력 페이지에서는 최소한 다음을 확인하세요.
- 입력 파일, 애플리케이션 유형, Java 버전, 모든 대상 플랫폼
- 아카이브 확장자, JIT 설정, 스캐너 오버레이, JVM 시작 옵션
- JavaFX와 WebView, Spring Boot 레이아웃, 또는 Tomcat 버전과 컨텍스트 경로
- 보호 대상으로 선택한 의존성 JAR와 모든 제외 규칙
- 출력 디렉터리, 그리고
p4jx-xxxx하위 디렉터리를 새로 만들지 여부
생성한 뒤에는 대상 플랫폼마다 패키지 안의 실행 스크립트로 시작, 프레임워크 스캔, 직렬화, 리플렉션, 리소스 로딩, 핵심 업무 흐름을 확인하세요. 고급 옵션을 올바르게 설정했다는 것은 작업 설정이 맞다는 뜻일 뿐, 최종 산출물 검증을 대신하지는 못합니다.