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 노드가 루트 노드의 마지막 자식 노드로 출력 파일에 기록됩니다.현재 서명 프로필은 다음과 같이 고정되어 있습니다:

항목	고정 값
서명 유형	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 서명, 요소 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 파일을 보관하는 것이 좋습니다.