sslTrusJarsigner 사용 가이드

준비 사항

사용 전에 다음을 준비해 주세요:

• JDK 8 이상 버전.
• sslTrusJarsigner-<version>.jar.
• Access Key, Access Secret 및 인증서 번호.
• 서명할 JAR 파일 또는 TIMS/1E XML 파일.

본문의 <version>, 자격 증명, 인증서 번호 및 파일 경로를 실제 값으로 바꿔 주세요.

다운로드

다음 페이지에서 최신 릴리스 패키지를 다운로드하세요:

최신 패키지 다운로드

ZIP 파일을 다운로드하고 압축을 풀면 다음 항목을 얻을 수 있습니다:

• sslTrusJarsigner-<version>.jar
• SHA-256 검증 파일

사용 전에 검증 파일로 JAR 파일의 무결성을 확인하는 것을 권장합니다.

실행 환경 확인

다음 명령을 실행하여 Java, jarsigner 및 도구 파일을 사용할 수 있는지 확인하세요:

java -version
jarsigner -help
java -jar sslTrusJarsigner-<version>.jar --version

도움말 정보 보기:

java -jar sslTrusJarsigner-<version>.jar --help

인증 정보 구성

Linux 및 macOS

export SSLTRUS_JARSIGNER_ACCESS_KEY="YOUR_ACCESS_KEY"
export SSLTRUS_JARSIGNER_ACCESS_SECRET="YOUR_ACCESS_SECRET"
export SSLTRUS_JARSIGNER_CERT_CODE="YOUR_CERT_CODE"

Windows PowerShell

$env:SSLTRUS_JARSIGNER_ACCESS_KEY = "YOUR_ACCESS_KEY"
$env:SSLTRUS_JARSIGNER_ACCESS_SECRET = "YOUR_ACCESS_SECRET"
$env:SSLTRUS_JARSIGNER_CERT_CODE = "YOUR_CERT_CODE"

서비스 담당자가 전용 서비스 주소를 제공한 경우, 다음 설정을 추가로 진행해야 합니다:

Linux 및 macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell：

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

전용 서비스 주소가 제공되지 않은 경우 이 변수를 설정하지 마십시오.

서명

다음 예시는 app-unsigned.jar에 서명한 후 app-signed.jar로 저장합니다. 고정 매개변수는 예시와 동일하게 그대로 사용하십시오.

JDK 9 이상 버전

Linux 및 macOS:

jarsigner \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerPath "sslTrusJarsigner-<version>.jar" \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerPath "sslTrusJarsigner-<version>.jar" `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

JDK 8

먼저 JAVA_HOME가(이) 완전한 JDK 8을 가리키는지 확인하십시오.

Linux 및 macOS:

jarsigner \
  -J-cp \
  -J"$JAVA_HOME/lib/tools.jar:sslTrusJarsigner-<version>.jar" \
  -keystore NONE \
  -storetype SSLTRUS \
  -storepass SSLTRUS \
  -providerClass com.racent.codesign.SSLTrusProvider \
  -sigalg SHA256withRSA \
  -tsa http://timestamp.sectigo.com \
  -signedjar "app-signed.jar" \
  "app-unsigned.jar" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell：

jarsigner `
  -J-cp `
  "-J$env:JAVA_HOME\lib\tools.jar;sslTrusJarsigner-<version>.jar" `
  -keystore NONE `
  -storetype SSLTRUS `
  -storepass SSLTRUS `
  -providerClass com.racent.codesign.SSLTrusProvider `
  -sigalg SHA256withRSA `
  -tsa http://timestamp.sectigo.com `
  -signedjar "app-signed.jar" `
  "app-unsigned.jar" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

참고

• 명령어 마지막의 인증서 번호는 SSLTRUS_JARSIGNER_CERT_CODE와 반드시 일치해야 합니다.
• 원본 JAR 파일을 덮어쓰지 않도록 항상 -signedjar로 새 파일을 생성할 것을 권장합니다.
• 타임스탬프가 필요하지 않은 경우 -tsa 및 그 뒤에 오는 주소를 삭제할 수 있습니다.

XML 서명(XMLDSig)

TIMS/1E XML은 sign-xml 명령어를 사용해 XML Digital Signature(XMLDSig) 봉입형(enveloped) 서명을 생성합니다. 개인 키는 원격 서명 서비스에만 계속 보관되며; 도구는 로컬에서 XMLDSig에 필요한 다이제스트와 서명 구조를 생성한 뒤, 원격 서비스에서 RSA 서명을 완료합니다.

Linux 및 macOS:

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE"

Windows PowerShell:

java -jar sslTrusJarsigner-<version>.jar `
  sign-xml `
  "input.xml" `
  "signed.xml" `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE"

서명 형식

생성된 서명은 XMLDSig 표준 네임스페이스 http://www.w3.org/2000/09/xmldsig#를 사용하며, Signature 노드는 루트 노드의 마지막 자식 노드로 출력 파일에 기록됩니다. 현재 서명 profile은 다음과 같이 고정되어 있습니다:

항목	고정값
서명 유형	Enveloped signature
서명 범위	전체 XML 문서, Reference URI=""
Reference Transform	Enveloped Signature Transform
Canonicalization	Inclusive Canonical XML 1.0
다이제스트 알고리즘	SHA-256
서명 알고리즘	RSA-SHA256
KeyInfo	X509Data，기본적으로 리프 인증서를 포함합니다

호출자는 직접 다이제스트를 계산하거나 SignatureValue를 구성할 필요가 없습니다. 도구는 원격 인증서의 리프 인증서로 KeyInfo/X509Data를 채우고 XML에 최종 SignatureValue를 기록합니다.

완전한 인증서 체인 포함

기본적으로 XML 크기를 줄이고 일반적인 TIMS/1E 파일과 일치하도록 리프 인증서만 출력됩니다. 수신 측에서 XML에 중간 인증서 체인을 포함하도록 요구하는 경우 명령어 끝에 --full-chain를 추가하세요:

java -jar sslTrusJarsigner-<version>.jar \
  sign-xml \
  "input.xml" \
  "signed.xml" \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  --full-chain

--full-chain는 KeyInfo/X509Data의 인증서 목록에만 영향을 미치며, 서명 범위, 다이제스트 알고리즘 또는 서명 알고리즘은 변경하지 않습니다. 이 옵션은 인증서 번호 앞이나 뒤에 배치할 수 있습니다. 인증서 번호를 제공하지 않으면 SSLTRUS_JARSIGNER_CERT_CODE이(가) 사용됩니다.

입력 및 사용 제한

• 입력은 올바른 형식의 XML이어야 하며 루트 노드를 포함해야 합니다.
• 입력 파일에 XMLDSig Signature 노드가 이미 포함되어 있으면 안 됩니다. 도구는 서명 범위를 확인할 수 없는 파일이 생성되는 것을 방지하기 위해 중복 서명을 거부합니다.
• 현재 전체 문서에 대한 enveloped 서명만 지원하며, detached signature, 요소 ID별 서명 또는 사용자 지정 XMLDSig 프로필은 지원하지 않습니다.
• 도구는 XML 외부 엔티티 및 외부 DTD 로드를 비활성화하므로 외부 엔티티 확장에 의존하는 XML은 허용되지 않습니다.
• 서명이 완료된 후 XML의 구조, 텍스트, 속성 또는 네임스페이스를 수정하지 마십시오. 이러한 변경은 XMLDSig 검증 실패로 이어집니다. 항상 원본 입력 파일을 보존하고 서명 결과를 새로운 출력 파일에 작성해야 합니다.

검증 파일 생성

서명 후 검증에 필요한 JKS 파일을 생성할 수 있습니다:

Linux 및 macOS:

java -jar sslTrusJarsigner-<version>.jar \
  generate-keystore \
  "$SSLTRUS_JARSIGNER_CERT_CODE" \
  "verify.jks" \
  "SSLTRUS"

Windows PowerShell：

java -jar sslTrusJarsigner-<version>.jar `
  generate-keystore `
  "$env:SSLTRUS_JARSIGNER_CERT_CODE" `
  "verify.jks" `
  "SSLTRUS"

verify.jks는 서명 검증 전용으로, 서명 실행에는 사용할 수 없습니다.

서명 검증

생성된 verify.jks를 사용해 서명된 JAR를 검증합니다:

jarsigner \
  -verify \
  -verbose \
  -certs \
  -keystore "verify.jks" \
  -storetype JKS \
  -storepass "SSLTRUS" \
  "app-signed.jar"

JAR의 서명 정보만 확인해야 하는 경우:

jarsigner -verify -verbose -certs "app-signed.jar"

자주 묻는 질문

Access Key, Access Secret 또는 인증서 번호 누락 안내

현재 터미널에 다음 환경 변수가 설정되어 있는지 확인하세요:

• SSLTRUS_JARSIGNER_ACCESS_KEY
• SSLTRUS_JARSIGNER_ACCESS_SECRET
• SSLTRUS_JARSIGNER_CERT_CODE

환경 변수를 설정한 후, 동일한 터미널 창에서 서명 명령을 실행해야 합니다.

非法选项: -providerPath 안내

현재 JDK 8을 사용 중입니다. 본 문서의 JDK 8 서명 명령으로 변경하여 사용하세요.

com.racent.codesign.SSLTrusProvider를 로드할 수 없다는 안내

다음 사항을 확인하세요:

• sslTrusJarsigner-<version>.jar 경로가 올바른지 확인하세요.
• 파일명의 버전 번호가 실제 파일과 일치하는지 확인하세요.
• JDK 8의 JAVA_HOME가 완전한 JDK를 가리키는지 확인하세요.

인증서 또는 alias를 찾을 수 없다는 안내

다음 사항을 확인하세요:

• 인증서 번호가 올바른지 확인하세요.
• 명령 끝의 인증서 번호가 환경 변수와 일치하는지 확인하세요.
• 현재 자격 증명에 해당 인증서를 사용할 권한이 있는지 확인하세요.

서명 요청 실패

다음 사항을 확인하세요:

• 네트워크 연결, 프록시 및 방화벽 설정을 확인하세요.
• 자격 증명과 인증서 번호가 올바른지 확인하세요.
• 전용 서비스 주소가 서비스 담당자가 제공한 내용대로 구성되었는지 확인하세요.

여전히 문제가 해결되지 않으면 전체 오류 메시지를 보관한 후 기술 지원에 문의하세요. 오류 메시지를 제출하기 전에 자격 증명을 삭제하거나 가려주세요.

타임스탬프 실패

현재 네트워크에서 명령의 타임스탬프 주소에 접근할 수 있는지 확인하세요. 업무상 허용된다면 -tsa와 그 뒤의 주소를 일시적으로 삭제한 후 서명을 다시 실행하여 문제를 파악할 수 있습니다.

보안 주의사항

• 소스 코드, 문서, 공유 스크립트 또는 이미지에 실제 Access Secret을 저장하지 마세요.
• 자격 증명이 포함된 명령줄, 터미널 기록 또는 파이프라인 로그를 외부에 공유하지 마세요.
• 자동화 환경에서는 보호된 키 변수를 사용하여 자격 증명을 주입해야 합니다.
• 신뢰할 수 있는 배포 채널에서 도구를 다운로드하고, 사용 전에 파일 무결성을 검증하세요.
• 서명되지 않은 원본 JAR 파일을 보관하는 것을 권장합니다.