Skip to main content

คู่มือการใช้งาน 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

การกำหนดค่า Credentials​

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
  • แนะนำให้ใช้ -signedjar สร้างไฟล์ใหม่เสมอ เพื่อหลีกเลี่ยงการเขียนทับ JAR ต้นฉบับ
  • หากไม่ต้องการ timestamp ให้ลบ -tsa และที่อยู่ที่ตามหลังออกได้

การลงนาม XML (XMLDSig)​

XML ของ TIMS/1E ใช้คำสั่ง 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 TransformEnveloped Signature Transform
CanonicalizationInclusive Canonical XML 1.0
อัลกอริทึมไดเจสต์SHA-256
อัลกอริทึมลายเซ็นRSA-SHA256
KeyInfoX509Data โดยค่าเริ่มต้นรวมถึงใบรับรอง leaf

ผู้เรียกใช้ไม่จำเป็นต้องคำนวณไดเจสต์เองหรือสร้าง SignatureValue เครื่องมือจะใช้ใบรับรอง leaf จากใบรับรองระยะไกลในการเติม KeyInfo/X509Data และเขียน SignatureValue สุดท้ายลงใน XML

รวมถึงสายใบรับรองที่สมบูรณ์​

ผลลัพธ์เริ่มต้นจะรวมเฉพาะใบรับรองปลายทางเท่านั้น เพื่อลดขนาดไฟล์ 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 profile แบบกำหนดเอง
  • เครื่องมือจะปิดใช้งานการโหลด XML external entity และ external 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 ถูกต้องหรือไม่
  • หมายเลขเวอร์ชันในชื่อไฟล์ตรงกับไฟล์จริงหรือไม่
  • JAVA_HOME ของ JDK 8 ชี้ไปยัง JDK ฉบับเต็มหรือไม่

แจ้งเตือนว่าไม่พบใบรับรองหรือ alias​

โปรดตรวจสอบ:

  • หมายเลขใบรับรองถูกต้องหรือไม่
  • หมายเลขใบรับรองท้ายคำสั่งตรงกับตัวแปรสภาพแวดล้อมหรือไม่
  • ข้อมูลประจำตัวปัจจุบันมีสิทธิ์ใช้ใบรับรองนั้นหรือไม่

คำขอลงนามล้มเหลว​

โปรดตรวจสอบ:

  • การเชื่อมต่อเครือข่าย พร็อกซี และการตั้งค่าไฟร์วอลล์
  • ข้อมูลประจำตัวและหมายเลขใบรับรองถูกต้องหรือไม่
  • ที่อยู่บริการเฉพาะถูกกำหนดค่าตามที่เจ้าหน้าที่บริการให้ไว้หรือไม่

หากยังไม่สามารถแก้ไขได้ โปรดเก็บข้อความข้อผิดพลาดฉบับเต็มและติดต่อฝ่ายสนับสนุนทางเทคนิค ก่อนส่งข้อความข้อผิดพลาด โปรดลบหรือปิดบังข้อมูลประจำตัว

การประทับเวลาล้มเหลว​

โปรดยืนยันว่าเครือข่ายปัจจุบันสามารถเข้าถึงที่อยู่การประทับเวลาในคำสั่งได้ หากธุรกิจอนุญาต สามารถลบ -tsa และที่อยู่ถัดจากนั้นชั่วคราว แล้วรันคำสั่งลงนามอีกครั้งเพื่อระบุปัญหา

ข้อควรระวังด้านความปลอดภัย​

  • อย่าบันทึก Access Secret จริงในซอร์สโค้ด เอกสาร สคริปต์ที่แชร์ หรืออิมเมจ
  • อย่าแชร์บรรทัดคำสั่ง ประวัติเทอร์มินัล หรือบันทึกไปป์ไลน์ที่มีข้อมูลประจำตัวแก่บุคคลภายนอก
  • สภาพแวดล้อมอัตโนมัติควรใช้ตัวแปรคีย์ที่ได้รับการป้องกันเพื่อแทรกข้อมูลประจำตัว
  • โปรดดาวน์โหลดเครื่องมือจากช่องทางเผยแพร่ที่น่าเชื่อถือ และตรวจสอบความสมบูรณ์ของไฟล์ก่อนใช้งาน
  • แนะนำให้เก็บไฟล์ JAR ต้นฉบับที่ยังไม่ได้ลงนามไว้
Last updated on