Skip to main content

คู่มือการใช้งาน sslTrusJarsigner

การเตรียมความพร้อม​

ก่อนใช้งาน กรุณาเตรียม:

  • JDK 8 หรือเวอร์ชันที่ใหม่กว่า
  • sslTrusJarsigner-<version>.jar
  • Access Key, Access Secret และหมายเลขใบรับรอง
  • ไฟล์ JAR ที่รอการลงนาม หรือไฟล์ XML TIMS/1E

กรุณาแทนที่ <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

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

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 ต้นฉบับ
  • หากไม่ต้องการประทับเวลา สามารถลบ -tsa และที่อยู่ที่ตามหลังได้

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

TIMS/1E XML ใช้คำสั่ง sign-xml เพื่อสร้างลายเซ็นแบบ enveloped ของ XML Digital Signature (XMLDSig) คีย์ส่วนตัวยังคงถูกเก็บไว้ในบริการลงนามระยะไกลเท่านั้น เครื่องมือจะสร้างโครงสร้างไดเจสต์และลายเซ็นที่จำเป็นสำหรับ 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 certificate

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

รวม certificate chain แบบเต็ม​

ตามค่าเริ่มต้น ผลลัพธ์จะรวมเฉพาะใบรับรองปลายทางเท่านั้น เพื่อลดขนาดไฟล์ 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 และ DTD ภายนอก จึงไม่รับ XML ที่ต้องอาศัยการขยายจาก external entity
  • หลังจากลงนามเสร็จแล้ว อย่าแก้ไขโครงสร้าง ข้อความ แอตทริบิวต์ หรือเนมสเปซของ 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