Skip to main content

การผสานรวม Java

sslTrus ให้บริการ sslTrusJarsigner Java Provider ซึ่งสามารถใช้งานร่วมกับเครื่องมือ jarsigner ที่มาพร้อมกับ JDK เพื่อลงนามไฟล์ Java JAR ผ่านบริการลงนามโค้ดระยะไกล

ในระหว่างกระบวนการลงนาม คีย์ส่วนตัวสำหรับการลงนามโค้ดจะถูกเก็บไว้ในคลาวด์ HSM ตลอดเวลา ฝั่งโลคอลมีหน้าที่สร้างข้อมูลที่รอการลงนามและโครงสร้างการลงนาม จากนั้นเรียกใช้บริการระยะไกลผ่าน sslTrusJarsigner Provider เพื่อดำเนินการลงนามด้วยคีย์ส่วนตัว

นอกเหนือจากการลงนาม JAR แล้ว sslTrusJarsigner ยังมีความสามารถในการลงนาม XMLDSig ซึ่งสามารถใช้ในสถานการณ์การลงนามดิจิทัล XML ได้

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

ก่อนใช้งานโปรดเตรียม:

  • JDK 8 หรือเวอร์ชันที่สูงกว่า
  • sslTrusJarsigner-<version>.jar
  • Access Key
  • Access Secret
  • หมายเลขใบรับรอง (Cert Code)
  • ไฟล์ JAR หรือไฟล์ XML ที่ต้องการลงนาม

<version> ข้อมูลรับรองการเข้าถึง หมายเลขใบรับรอง และเส้นทางไฟล์ในตัวอย่างของบทความนี้ ล้วนต้องแทนที่ด้วยค่าจริง

ดาวน์โหลด sslTrusJarsigner​

ดาวน์โหลดแพ็กเกจรุ่นล่าสุดจาก หน้าปล่อย sslTrusJarsigner และแตกไฟล์

แพ็กเกจที่เผยแพร่ประกอบด้วย:

sslTrusJarsigner-<version>.jar
SHA-256 校验文件

ขอแนะนำให้ตรวจสอบความสมบูรณ์ของไฟล์ sslTrusJarsigner-<version>.jar ด้วยการตรวจสอบค่า SHA-256 ก่อนการใช้งาน

ตรวจสอบสภาพแวดล้อมการทำงาน​

ขั้นแรกยืนยันว่า jarsigner ที่มาพร้อมกับ Java และ JDK สามารถใช้งานได้ตามปกติ:

java -version
jarsigner -help

ตรวจสอบเวอร์ชัน sslTrusJarsigner:

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

ดูความช่วยเหลือ:

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

หากไม่มีคำสั่ง jarsigner โปรดตรวจสอบว่าปัจจุบันติดตั้ง JDK แบบเต็มรูปแบบ ไม่ใช่เพียงสภาพแวดล้อมรันไทม์ที่มีเฉพาะ Java Runtime

การกำหนดค่าข้อมูลประจำตัวสำหรับการเข้าถึง​

sslTrusJarsigner อ่านข้อมูลประจำตัวสำหรับการเข้าถึงบริการลงนามโค้ดระยะไกลและหมายเลขใบรับรองผ่านตัวแปรสภาพแวดล้อม

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"

หากเจ้าหน้าที่บริการให้ที่อยู่บริการเฉพาะมา ยังต้องตั้งค่า SSLTRUS_JARSIGNER_URL อีกด้วย

Linux และ macOS:

export SSLTRUS_JARSIGNER_URL="YOUR_SERVICE_URL"

Windows PowerShell:

$env:SSLTRUS_JARSIGNER_URL = "YOUR_SERVICE_URL"

หากไม่มีการระบุที่อยู่บริการเฉพาะ ก็ไม่จำเป็นต้องตั้งค่าตัวแปรนี้

Access Secret เป็นข้อมูลรับรองที่มีความละเอียดอ่อน ไม่ควรเขียนลงในซอร์สโค้ด ไฟล์กำหนดค่าสาธารณะ หรือบันทึกการ build สำหรับสภาพแวดล้อมอัตโนมัติ แนะนำให้ฉีดผ่าน CI/CD Secret หรือกลไกการจัดการข้อมูลรับรองอื่นๆ

การลงนาม JAR​

sslTrusJarsigner ผสานรวมกับเครื่องมือมาตรฐาน jarsigner ผ่านกลไก Java Security Provider

ตัวอย่างด้านล่างจะ:

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​

JDK 8 มีวิธีการโหลด Provider ที่แตกต่างจาก JDK 9 และเวอร์ชันที่ใหม่กว่า

ขั้นแรกให้ตรวจสอบ:

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 ต้นฉบับ
  • ตัวอย่างใช้ SHA256withRSA เพื่อลงนามโค้ดให้เสร็จสมบูรณ์
  • หากไม่ต้องการการประทับเวลา สามารถลบ -tsa และที่อยู่การประทับเวลาที่ตามหลังออกได้

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

แนะนำให้เพิ่มการประทับเวลาที่เชื่อถือได้สำหรับการลงนาม JAR ที่จะเผยแพร่อย่างเป็นทางการ

ในตัวอย่างใช้:

http://timestamp.sectigo.com

พารามิเตอร์ที่เกี่ยวข้อง:

-tsa http://timestamp.sectigo.com

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

หากต้องการใช้บริการประทับเวลาอื่น สามารถแทนที่ที่อยู่หลัง -tsa ด้วยที่อยู่ TSA ที่สอดคล้องกับนโยบายการลงนามจริง

เกี่ยวกับบริการประทับเวลาที่แตกต่างกันและการเลือกใช้ในสภาพแวดล้อมการผลิต โปรดดู เอกสารอ้างอิง

ลายเซ็น XML​

sslTrusJarsigner ยังมอบความสามารถในการลงนามดิจิทัล XML อีกด้วย

ไฟล์ XML สามารถสร้าง XMLDSig Enveloped Signature ผ่านคำสั่ง sign-xml

ในระหว่างกระบวนการลงนาม ฝั่งโลคัลจะรับผิดชอบการสร้างไดเจสต์และโครงสร้างลายเซ็นที่จำเป็นสำหรับ 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"

ผลลัพธ์ที่ได้ตามค่าเริ่มต้น KeyInfo จะมีเฉพาะใบรับรองลีฟเท่านั้น หากผู้รับต้องการให้ XML มีเชนใบรับรองครบถ้วน สามารถเพิ่มพารามิเตอร์ --full-chain ต่อท้ายคำสั่งได้

หลังจากการดำเนินการเสร็จสิ้น:

input.xml

สำหรับไฟล์ XML ต้นฉบับ

signed.xml

สำหรับไฟล์ผลลัพธ์ที่มีลายเซ็นดิจิทัล XML

คีย์ส่วนตัวสำหรับการลงนามโค้ดจะไม่ถูกเขียนลงในไฟล์ XML และจะไม่ถูกบันทึกลงในเครื่องคอมพิวเตอร์

การสร้างไฟล์สำหรับการตรวจสอบ​

หลังจากลงนามเสร็จสิ้น คุณสามารถสร้างไฟล์ 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

ไฟล์นี้ใช้สำหรับการตรวจสอบลายเซ็นเท่านั้น ไม่สามารถใช้ดำเนินการลงนามโค้ดได้

คีย์ส่วนตัวสำหรับการลงนามโค้ดยังคงถูกเก็บไว้ใน HSM ระยะไกล และจะไม่ถูกเขียนลงใน verify.jks

ตรวจสอบลายเซ็น JAR​

ใช้ verify.jks ที่สร้างขึ้นเพื่อตรวจสอบลายเซ็น:

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

หากต้องการเพียงตรวจสอบข้อมูลลายเซ็นที่มีอยู่แล้วในไฟล์ JAR ให้เรียกใช้คำสั่ง:

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

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

จำนวนครั้งในการลงนาม​

จำนวนครั้งในการลงนามของ Jarsigner จะนับตามการดำเนินการลงนามระยะไกลที่สำเร็จจริง

โดยทั่วไป:

การดำเนินการจำนวนครั้งในการลงนาม
ลงนามไฟล์ JAR หนึ่งไฟล์สำเร็จหนึ่งครั้ง1 ครั้ง
ลงนาม JAR 3 ไฟล์แยกกัน3 ครั้ง
ลงนาม JAR ไฟล์เดียวกันอีกครั้งหนึ่งเพิ่มอีก 1 ครั้ง
jarsigner -verify ตรวจสอบลายเซ็น0 ครั้ง
สร้าง verify.jks0 ครั้ง

ดังนั้น จำนวนครั้งในการลงนามจึงขึ้นอยู่กับจำนวนครั้งของการดำเนินการลงนามที่สำเร็จจริงเป็นหลัก ไม่ใช่จำนวนไฟล์ซอร์สโค้ดของโปรเจกต์ Java

โปรดศึกษากฎโดยละเอียดได้ที่ เอกสารอ้างอิง

คำถามที่พบบ่อย​

ขาด Access Key, Access Secret หรือหมายเลขใบรับรอง​

โปรดยืนยันว่าเทอร์มินัลปัจจุบันได้ตั้งค่าไว้แล้ว:

SSLTRUS_JARSIGNER_ACCESS_KEY
SSLTRUS_JARSIGNER_ACCESS_SECRET
SSLTRUS_JARSIGNER_CERT_CODE

After setting the environment variables, you need to execute the signing command in the same terminal session.

Invalid option: -providerPath​

If the following appears:

Invalid option: -providerPath

โดยทั่วไปบ่งชี้ว่ากำลังใช้งาน JDK 8

JDK 8 ไม่ใช้พารามิเตอร์ -providerPath ที่ปรากฏในตัวอย่างของ JDK 9 ขึ้นไป โปรดใช้คำสั่งสำหรับ JDK 8 ที่ระบุในบทความนี้แทน

ไม่สามารถโหลด SSLTrusProvider​

หากมีข้อความแจ้งว่าไม่สามารถโหลดได้:

com.racent.codesign.SSLTrusProvider

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

  • เส้นทาง sslTrusJarsigner-<version>.jar ถูกต้องหรือไม่
  • หมายเลขเวอร์ชันในชื่อไฟล์ตรงกับไฟล์จริงหรือไม่
  • JAVA_HOME ในสภาพแวดล้อม JDK 8 ชี้ไปยัง JDK เต็มรูปแบบหรือไม่

ไม่พบใบรับรองหรือ alias​

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

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

คำขอลายเซ็นระยะไกลล้มเหลว​

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

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

เมื่อตรวจสอบปัญหา สามารถเก็บข้อมูลข้อผิดพลาดทั้งหมดไว้ได้ แต่ก่อนส่งบันทึกหรือภาพหน้าจอข้อผิดพลาด ควรลบหรือปกปิดข้อมูลรับรองที่ละเอียดอ่อน เช่น Access Secret

การประทับเวลาไม่สำเร็จ​

ยืนยันว่าเครือข่ายปัจจุบันสามารถเข้าถึงเซิร์ฟเวอร์ประทับเวลาที่ระบุโดย -tsa ได้

หากธุรกิจอนุญาต สามารถลบออกชั่วคราวได้:

-tsa <URL>

ดำเนินการเซ็นชื่ออีกครั้ง เพื่อระบุว่าปัญหาเกิดขึ้นในขั้นตอนการเซ็นชื่อโค้ดระยะไกล หรือขั้นตอนการร้องขอ Timestamp

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

ระหว่างการผสานรวม Java ควรคำนึงถึงสิ่งต่อไปนี้:

  • Access Secret ควรจัดเก็บเป็นข้อมูลประจำตัวที่มีความละเอียดอ่อน
  • อย่าคอมมิตข้อมูลประจำตัวสำหรับการเข้าถึงไปยัง Git Repository
  • อย่าแสดง Access Secret แบบเต็มในบันทึก
  • verify.jks ใช้สำหรับการตรวจสอบเท่านั้น และไม่มี Private Key ที่ใช้สำหรับการเซ็นชื่อระยะไกล
  • sslTrusJarsigner Provider ภายในเครื่องไม่จัดเก็บ Private Key สำหรับการเซ็นชื่อโค้ด
  • การดำเนินการเซ็นชื่อด้วย Private Key จะดำเนินการโดยบริการเซ็นชื่อโค้ดระยะไกลเสมอ
  • ในสภาพแวดล้อมอัตโนมัติ แนะนำให้ใช้ CI/CD Secret หรือระบบจัดการข้อมูลประจำตัวเฉพาะเพื่อป้อนข้อมูลประจำตัวสำหรับการเข้าถึง

วิธีการผสานรวมที่เกี่ยวข้อง​

หากไฟล์ที่ต้องการเซ็นชื่อไม่ใช่ไฟล์ Java JAR หรือ XML สามารถเลือกวิธีการผสานรวมอื่นตามลักษณะการใช้งานจริง:

สถานการณ์วิธีการผสานรวม
เซ็นชื่อไฟล์ EXE, DLL, MSI ฯลฯ ผ่านบรรทัดคำสั่งโดยตรงเครื่องมือไคลเอนต์
Microsoft SignTool, Visual Studio และเครื่องมือ Windows อื่น ๆWindows Provider
GitHub Actions, Electron Builder และการบิลด์อัตโนมัติอื่น ๆCI/CD และเครื่องมือบิลด์
พัฒนาไคลเอนต์การเซ็นชื่อระยะไกลด้วยตนเองการผสานรวม API
Last updated on